USWDS Boilerplate

A starting point for publishing a site using Jekyll, GitHub Pages, and a hosted version of the U.S. Web Design System

This template is set up with USWDS core CSS and JS files from CDNJS.

• Last updated: September 12, 2021
• Version: 2.12.1
• More information: How to use USWDS

Use template on GitHub.

Or try it out first on CodePen.

Getting started

Copying the template and setting up publishing

1. Press the Use this template button on the Code tab.
2. Go to the Settings tab and scroll down to the GitHub Pages section.
3. Set the Source to main and press Save.

You'll see a URL show up, but the site takes a few minutes before it's actually live. In the meantime, try creating a page.

Creating your first page

1. Go to the Code tab.
2. Press the Add File button and select Create new file.
3. Give the page a title, for example, first-page.md. (Note the lack of spaces and the inclusion of the .md extension.)
4. Add some content using markdown syntax. For example, you could start with a heading and paragraph like this:

# First page
This is my first page.

5. Scroll down to the bottom of the page and press Commit new file.

Checking your page online

1. On the Code tab, find and press the Environments link. (It may be in the right column.)
2. On the next page (Deployments), press the View deployment button. (You should see the default homepage load.)
3. In the address bar of the browser, add the name of your page using the HTML extension and press return. For example: first-page.html. (The full address will be something like this: https://pglevy.github.io/uswds-boilerplate/first-page.html)

You should see the new page you created.

Next steps

Now that you know how to create pages, here are some other things you can do:

• Create more pages.
• Update index.md (the homepage) with your own content.
• Add links between pages so it works like a website.
• Copy component code snippets from the U.S. Web Design System to add more advanced functionality to your pages.

What to do if you're having problems

• Try starting over with a new repository and follow the instructions again.
• If it's still not working, create an issue in the original repo, and I'll try to help.

Building the running the site locally on your computer (for advanced users)

To run the site locally, you'll need to install Jekyll, which requires a few steps. See the official installation instructions.

Credit and license

This project was created primarly using the GitHub Pages gem for Jekyll and some inspiration from HTML5 Boilerplate. It is licensed under The Unlicense, which allows everything and promises nothing. 😎