jekyll-theme-uswds

A Jekyll theme that provides the U.S. Web Design System SASS and asset files. This theme makes it easy for web developers to focus on making customizations on top of the Web Design System for your site. Similar to how the Web Design System is not a "theme" but a toolkit for building websites, this project is less of a theme and more of a foundation for building Jekyll websites based on the Web Design System.

You will not find comprehensive templates implementing USWDS components, but any examples could be copy/pasted and used. If you're looking for a theme that includes the USWDS component library as templates, take a look at uswds-jekyll.

Installation

Add this line to your Jekyll site's Gemfile:

gem "jekyll-theme-uswds"

And add this line to your Jekyll site's _config.yml:

theme: jekyll-theme-uswds

And then execute:

$ bundle

Or install it yourself as:

$ gem install jekyll-theme-uswds

Usage

TODO: Write usage instructions here. Describe your available layouts, includes, sass and/or assets.

Development

To set up your environment to develop this theme, run npm install.

Your theme is setup just like a normal Jekyll site! To test your theme, run npm start and open your browser at http://localhost:4000. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.

When your theme is released, only the files in _layouts, _includes, _sass and assets tracked with Git will be bundled. To add a custom directory to your theme-gem, please edit the regexp in jekyll-theme-uswds.gemspec accordingly.

Bumping USWDS

Update the uswds version in package.json.

Pull the latest assets into the theme.

$ npm install
$ npm run clean
$ npm run uswds

Build the gem.

$ npm run gem:build

If you like, inspect the gem in pkg/.

Publish the gem to rubygems.org.

$ npm run gem:release

Build commands

npm run uswds

This copies the latest assets from the USWDS npm package.

npm run gem:build

Builds the theme into a gem for publishing on rubygems.org

npm run gem:install

Builds and installs the gem.

npm run gem:release

Publishes the gem on rubygems.org.

npm run clean

Removes the generated build files.

Release

Publishing to rubygems is handled by CI. To trigger the release, you need to bump the version as per semver and push a new git tag.

Determine the new version e.g. v0.1.0.

Bump the version in federalist-basic-report-theme.gemspec. Then update the dependencies.

$ bundle install

Commit the changes and create a new PR. Once merged, create a new git tag.

$ git checkout master && git pull
$ git tag $version
$ git push origin $version

Contributing

See CONTRIBUTING for additional information.

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.