Compatibility with the US Web Design Standards?

[cew821]

Hi Folks - Curious if anyone knows of a similar "guide" template that has the Web Design standards baked in? It seems the Design Standards docs themselves are largely modeled on this theme.

Basically, I'm looking to create up a content-focused Jekyll site that matches the styles of the Design Standards docs. Forking the design standards is one way forward, but I'd prefer to start with a "blank slate" that is similar to this template. Thanks for any pointers!

[cew821]

Not hearing anything about this, I built a new Jekyll template that matches the web design standards. You can check it out here: www.github.com/usds/USWDS-docs-template

[afeld]

Sorry for not seeing this sooner @cew821. Now realizing there are a few very similar themes and templates that use them floating around:

• https://github.com/18F/guides-style (theme) -> https://github.com/18F/guides-template (template)
• https://github.com/18F/uswds-jekyll (theme) -> https://github.com/18F/federalist-uswds-template (template)
• https://github.com/usds/USWDS-docs-template (template)

Would really like to pick a theme and corresponding template and focus our efforts. I don't have strong feelings about which one, and don't think it would be terribly hard to merge the features.

/cc @line47 @hursey013 @mattbailey0

[wslack]

I would prefer the guides template as a go-to for documentation sites (doesn't cover landing pages, but that's ok)

[toolness]

The last commit to the USDS one is from August 2016, which implies that, aside from not having a lot of activity, it's using a fairly old version of the standards. The docs there also seem to have a bunch of TODOs in them and seem relatively sparse.

In contrast, https://github.com/18F/uswds-jekyll has lots of docs, and has most recently been updated by @line47 to use the very latest version of the standards.

So between those two, I'd pick the 18F/uswds-jekyll one. Not sure how to choose between that and guides-style, though.

[afeld]

@toolness I'm assuming that USWDS would be more than happy to deprecate theirs if we have a maintained Jekyll theme that meets the need. USDS folks, let me know if that's not the case!

Given that https://github.com/18F/uswds-jekyll seems to be a simplified superset of https://github.com/18F/guides-style, I'm leaning towards that. I'm going to try converting a couple sites to see what it takes, and if there are limitations.

[wslack]

As long as its easy to edit the uswds-jekyll, I'm find with that; I've gotten feedback that the Federalist template was tricky to understand and manage.

[cew821]

Yes USDS would be happy to deprecate ours, wish I never had to make one.

Does the uswds-Jekyll theme work on github pages’ Jekyll?

[line47]

I have been working with the USWDS-Jekyll theme recently as @toolness mentioned and pulled some functionality from the guides-style such as search to incorporate.

My thoughts are in line with what @afeld is proposing; Deprecate other themes so we can focus on one that utilizes the USWDS and meets the needs of those using other themes. The USWDS-Jekyll theme has been used on a few sites now and I feel that the documentation is quite robust.

As far as conversion from the guides-style to the USWDS-jekyll you can take a look at this PR for the front end guide. 18F/frontend#181
@afeld I'd love to pair with you on some conversion sessions too 🎉

I'd propose we add issues to the USWDS-Jekyll repo for any necessary functionality that the Guides-style or other themes may have.

@hursey013 and @hbillings I'd ❤️ your thoughts here too!

[hursey013]

@cew821 uswds-jekyll is also a gem based theme so unfortunately it won't work with Github pages directly. I've been following the progress of this plugin though, which if it gets whitelisted by Github would allow uswds-jeykll (and any other gem based theme) to work on Github Pages.

[wslack]

If someone wants to fork and modify a copy of the template, do they also have to copy and modify a fork of the style repo? How do edits/modifications work?

[line47]

@wslack - with USWDS-Jekyll the USWDS styles are included and would not need to be pulled from a separate repo.

[wslack]

I'm confused. https://github.com/18F/federalist-uswds-template is a template. It has content. It does not have styles. I'm trying to see if we can put https://github.com/18F/federalist-uswds-template and USWDS-Jekyll together.

[line47]

If you create a new USWDS Website from Federalist it is using https://github.com/18F/federalist-uswds-template. I'm unsure on why the Federalist template was built separately from https://github.com/18F/uswds-jekyll.

Maybe someone on the thread has more insight than I do?
I'd love to combine these though! 👍

[wslack]

That's how Shawn did it, but I'm honestly unsure why. That's the main attractor to the guides template.

@shawnbot so he can see this later when he's not baby parenting

[hursey013]

I think it makes sense to keep them separate. federalist-uswds-template represents what an end user of the theme should see - a bare bones repo that is solely focused on content. All of the "behind the scenes" stuff like assets, includes, layouts, and plugins are brought in through uswds-jekyll and are totally invisible to the user and helps to keep the repo clean and uncluttered. The only reason any of those files would need to be added to a repo would be if folks wanted to customize or override the included layouts.