Name: uswds-site
Owner: U.S. Web Design System
Description: U.S. Web Design System website and documentation
Created: 2016-07-27 14:32:49.0
Updated: 2018-02-15 18:20:59.0
Pushed: 2018-02-21 00:56:53.0
Homepage: https://designsystem.digital.gov
Size: 24077
Language: HTML
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
This repo includes code and documentation for the U.S. Web Design System website. For information on the Design System (components) themselves, please visit web-design-standards.
Note that this README includes steps to pull the latest version of the Design System into your local instance of the documentation.
The U.S. Web Design System documentation is built using Jekyll for the file framework, gulp for task management, and the node module for the Design System.
You will need to have the following installed on your machine before following the commands below:
Some parts of the documentation are built using gulp.
To work on the site, switch to your local copy of the repository in terminal then run the following command to install project dependencies:
install
Now that all of your dependencies are installed, you can run your local server by running the following command:
start
Go to 127.0.0.1:4000
in your browser ? you should be viewing a local instance of designsystem.digital.gov.
Here are a few other utility commands you may find useful:
npm run clean
: Cleans out copied-over dependency assets.
npm run lint
: Runs eslint
and sass-lint
against JavaScript and Sass files.
npm test
: Runs all tests and linters.
npm run watch
: Runs a series of commands that watches for any changes in both the Design System node module and the root level asset folders in this repo.
npm start -- --incremental
: Runs your local server with incremental regeneration enabled to greatly improve build time. Use instead of npm start
.
uswds
packageSometimes you will want to use the latest version of the web-design-standards
repo. Follow these steps to do so:
web-design-standards
repo.npm install
to install the dependencies required for the package in the web-design-standards
directory.npm run build
to create the built version of the Design System in the web-design-standards
directory.npm link
in the root level of the web-design-standards
directory on your local machine.npm link uswds
in the root level of the web-design-standards-docs
directory on your local machine.FRACTAL_BASE_URL
env var to the running fractal instance for web-design-standards
. In your terminal window in the web-design-standards-docs
directory, enter export FRACTAL_BASE_URL="http://127.0.0.1:3000"
.npm run watch
in both project directories to have changes automatically built and compiled on changes to any asset files.npm start
in the web-design-standards-docs
directory to start the Jekyll server locally.You are now using the latest version of the Design System via your cloned version on your local machine. To stop using this version, type npm unlink uswds
from the root level of the web-design-standards-docs
directory.
The Design System uses the fractal design system builder to organize and document the components. This documentation site pulls the components from fractal to showcase them on the site. This is done with a custom fractal_component
Jekyll tag, which takes the full name of the fractal component as a parameter.
This site is deployed on Federalist, which automatically builds the site whenever commits are pushed to master
.
Federalist also builds public previews for each branch pushed to GitHub. For instance, to see the latest build of the develop
branch, visit:
https://federalist.fr.cloud.gov/preview/18f/web-design-standards-docs/develop/
To update the version of USWDS being used, change the version that
package.json
specifies in its dependencies
section.
We currently pull USWDS via git rather than npm, as it allows us to use any tag or commit during development. To install a specific commit, you can use e.g.:
install --save "uswds/uswds#fb49e4f"
Alternatively, to use a specific version tag, use e.g.:
install --save "uswds/uswds#v1.3.1"
This version number or commit hash is automatically parsed when the site
is built and used for display on the site (see _plugins/uswds_version.rb
for details). Therefore, be sure to use an actual version tag on all
master
branch commits–otherwise a commit hash will show up as the
version on the production site, which would be confusing.
See the _posts
directory for instructions on adding updates.
Some of the content on the documentation site is dynamically fetched from
GitHub. If you want to ensure that its API won't rate-limit you, you
may want to
create an access token
and assign it to your GITHUB_ACCESS_TOKEN
environment variable.
The dynamic content is stored in the .jekyll_get_cache
directory and
won't be re-fetched once it's cached there. However, this means that your
data can get stale over time, so if you want to ensure that your site
is using the very latest data, you'll want to clear the cache by running:
rf .jekyll_get_cache
Please read through our contributing guidelines. These guidelines are directions for opening issues and submitting pull requests, and they also detail the coding and design standards we follow.