The USDS website is built with:
- Jekyll via the github-pages gem
- See current dependencies for GitHub Pages
- U.S. Web Design System (USWDS)
Before getting started, install the following on your system:
We recommmend that you use a Docker container to run the site as a development environment because of dependency and version collisions. This allows the site to run in a contained place, minimizing setup issues.
docker build -t usds-website . --no-cache
Run this command to have a local version on http://localhost:4080.
docker run -p 4080:4000 --name usdsweb usds-website
If you want to make changes and have them update on the running container
we need to map the active source code in to the container with a volume mount and
expose the port for livereload. This should ensure that changes you make are being
mapped to the /app director and refresh on the running container. Note the volume mount syntax
for pwd might be different on Windows or a non Bash shell.
docker run -p 4080:4000 -p 35729:35729 -v $(pwd):/app --name usdsweb usds-website
Builds staging Jekyll site using JEKYLL_ENV=staging. Staging builds are used for temporary testing on cloud.gov. Do not deploy a staging build to GitHub pages.
Staging sites are one-off, per-user builds in a cloud.gov sandbox. Handy for testing and gathering feedback.
To create a cloud.gov staging build:
npm run build-staging- Log in to cloud.gov cli,
cf(TODO: details here) cf push
If you haven't used cloud.gov before, you'll want to set up
- Determine if you have access to cloud.gov and follow instructions to sign up.
- Log in to your cloud.gov dashboard and install and configure Cloud Foundry.
A successful push will print a staging url next to routes, ex: website-staging-foo-bar-ab.app.cloud.gov. Visit the staging url to preview your build.
We use USWDS version 3. Most of the styles are built off of v2.12.0, but the underlying framework is v3. The scss is in assets/stylesheets/uswds, with the entry of index.scss. uswds-settings.scss has custom variables and styles.scss has custom scss.
Custom USWDS theme settings are declared in assets/stylesheets/uswds/_uswds-theme-*.scss. Use these files to add or remove utilities, edit variables, or change how the design system builds.
After updating, make a new build or restart your localhost to see any changes.
To update a major version of uswds, consult their documentation. The package.json settings will allow for minor and patch updates as a matter of course.
- /images: This folder contains editorial photos and other images for People cards and pages, Project cards and pages, event logos for the Events cards and page, and other areas that are likely to change semi-frequently.
- /assets/img: Site assets and evergreen images such as page banners/headers and vector graphics should be placed in the assets/img folder here. The images in this folder typically will not be subject to change.