U.S. Web Design System (USWDS) Documentation Website

Welcome! This repository contains the code for the U.S. Web Design System (USWDS) documentation website. If you're looking for the main USWDS components and codebase, head over to our USWDS repository.

Running the Website Locally

This site is built using:

• Jekyll, a static site generator
• Gulp.js, for task automation
• USWDS npm package, stable version

Follow the steps below to set up the site on your local machine.

Prerequisites

Before getting started, make sure you have the following installed:

1. Git – Installation guide

2. Ruby – Version specified in .ruby-version or .tool-versions

   • Installation guide

3. Node.js – Version specified in .nvmrc or .tool-versions

   • Installation guide

4. Bundler – Version specified in .bundler-version

   • Installation guide

⚠️ Ubuntu 20.04 Users

If you encounter this error:

bundler: failed to load command: jekyll (/usr/share/rvm/gems/ruby-3.0.2/bin/jekyll)

Fix it by running:

gem install ffi -- --disable-system-libffi

Installation

1. Clone the repository:

   git clone [email protected]:uswds/uswds-site.git
   

2. Navigate into the project folder:

   cd uswds-site
   

3. Install dependencies:

   npm install
   bundle install
   

4. Start the local server:

   npm start
   

5. View the site in your browser:
   Open http://127.0.0.1:4000 to see the site running locally.

Useful Commands

Here are some additional commands you may find helpful:

• npm run clean – Removes copied dependency assets.
• npm run lint – Runs eslint and sass-lint to check for coding issues.
• npm test – Runs all tests and linters.
• npm run watch – Watches for changes and automatically rebuilds the site.
• npm start -- --incremental or npm run serve – Runs the site with incremental regeneration to speed up build times.

Using the Development Version of USWDS

If you need to work with the latest development version of USWDS, follow these steps:

1. Clone the uswds repository:

   git clone https://github.com/uswds/uswds.git
   

2. Navigate to the uswds directory and install dependencies:

   cd uswds
   npm install
   

3. Build USWDS:

   npm run build
   

4. Link USWDS to your local setup:

   npm link
   

5. Go back to uswds-site and link it to the local USWDS version:

   cd ../uswds-site
   npm link uswds
   

6. Start the uswds development server:

   npm start
   

7. Set the LIBRARY_BASE_URL environment variable:

   export LIBRARY_BASE_URL="http://127.0.0.1:6006"
   

8. Start the USWDS documentation site:

   npm run serve
   npm run watch
   

📝 Note: Changes to USWDS won’t automatically rebuild the site—you’ll need to manually trigger a rebuild.

To unlink the development version, run:

npm unlink uswds

Components

This site displays USWDS components using pre-built HTML templates from the html-templates directory. These templates are integrated using a custom library_component Jekyll tag.

Deployment & Previews

The site is deployed using cloud.gov Pages.

• Changes pushed to the main branch will automatically update the live site.
• Public previews are generated for each branch pushed to GitHub.

⚠️ If a new section fails to build on Pages, try clearing the cache:

bundle update

Updating the USWDS Version

USWDS code base is included as a Git dependency in package.json. To update it:

• To install a specific commit:

  npm install --save "uswds/uswds#commit-hash"
  

• To install a specific version tag:

  npm install --save "uswds/uswds#v1.3.1"
  

The version number is automatically detected and displayed on the site. Always use an official version tag for main branch commits to avoid confusion.

Adding Content to the "Updates" Section

To add an update, see the instructions in the _posts directory.

Dynamic Content

Some content on this site is dynamically fetched from GitHub. To avoid API rate limits, you may want to:

1. Create a GitHub access token: Guide
2. Set the token in your environment:

   export GITHUB_ACCESS_TOKEN="your-token-here"
   

If you notice outdated data, clear the cache with:

rm -rf .jekyll_get_cache

Contributing

We welcome contributions! Please review our contributing guidelines before opening an issue or submitting a pull request. These guidelines cover our coding standards and best practices.

🎉 Thanks for Supporting USWDS!

We appreciate your contributions to making digital services better and more accessible for everyone. 🚀