Compatibility with the US Web Design Standards?

[18f]

Compatibility with the US Web Design Standards?

[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.

[line47]

@hursey013 - thanks for that. I was thinking it was something similar. Allowing control over what Release of USWDS-Jekyll gets pushed back into Federalist. For example the USWDS-Federalist-theme could be at version 1.5.0 while the USWDS-Jekyll is at version 1.6.0.

[wslack]

@hursey013 every Federalist customer is always going to want to customize or override the layout in some way. The only folks that won't are 18F internal. @thecapacity has been working on doing some of that customization, for example.

[hursey013]

@wslack I agree folks will want to customize, that's what I'm doing with plainlanguage.gov, but instead of including the entire kitchen sink I can selectively choose which files I want to override and only add those to the repo (while everything else will continue to be inherited from the theme). If we include everything within uswds-jekyll in each new USWDS Federalist site it would defeat the purpose of using a theme at all.

[wslack]

hmm ok - do we have instructions on how to do that anywhere? Some of our partners won't want to depend on 18F controlled code for their sites.

I guess I'm saying that for some partners, having a template that relies on an external theme will not meet their needs.

[hursey013]

Customization of the theme is covered here: https://github.com/18F/uswds-jekyll#customization

If it makes more sense for partners to have the theme baked in, that's definitely a possibility too, and in that case you are right, we could completely eliminate the need for federalist-uswds-template. Instead new USWDS sites would just clone the uswds-jekyll repo (with some minor post-processing to cleanup unnecessary files) and then they would have direct access to all files within the theme.

[wslack]

(first, I know I'm being a little pushy and I appreciate the patience)

I wonder if I should step back and consider the different goals here. If we want a canonical USWDS template, that seems like a reasonable thing to decide on. I get the we need a focal template for the USWDS work - and USWDS-Jekyll seems good for that.

However, if we centralize to a single repo we make it harder for Federalist partners to be able to customize from a template that's closer to their own use case. Federalist's goal is to have a variety of USWDS-utilizing templates. Should we split up this conversation?

[afeld]

There is a compromise option. Jekyll's gem-based themes are structured the same as Jekyll sites on their own, so the same repository can be used as a gem, or forked and used as a base template. We could essentially say

If you are ok to work within ____ constraints (given _____ benefits), fork https://github.com/18F/federalist-uswds-template. If you want to have greater control, but also greater responsibility, fork https://github.com/18F/uswds-jekyll.

That might be too hard to explain to users, though...?

[wslack]

If we only offer the gem, we'll have to explain it anyway for them to make any edits, so that sounds good to me as long as it isn't expensive, maintenance wise.

[afeld]

It's definitely the lowest maintenance option, yeah.