All Projects → uswds → Uswds Site

uswds / Uswds Site

Licence: other
USWDS website and documentation

Projects that are alternatives of or similar to Uswds Site

Just The Docs
A modern, high customizable, responsive Jekyll theme for documention with built-in search.
Stars: ✭ 3,747 (+2675.56%)
Mutual labels:  documentation, jekyll, scss
Docs
Parse Platform docs
Stars: ✭ 296 (+119.26%)
Mutual labels:  documentation, jekyll, scss
Long Haul
A minimal, type-focused Jekyll theme.
Stars: ✭ 524 (+288.15%)
Mutual labels:  gulp, jekyll, scss
Sassdoc
Release the docs!
Stars: ✭ 1,353 (+902.22%)
Mutual labels:  documentation, scss
Jekyll Rtd Theme
Just another documentation theme compatible with GitHub Pages
Stars: ✭ 92 (-31.85%)
Mutual labels:  documentation, scss
Bootstrap 4 Github Pages
A Bootstrap 4 template project for Github Pages and Jekyll
Stars: ✭ 96 (-28.89%)
Mutual labels:  jekyll, scss
Interior
Design system for the modern web.
Stars: ✭ 77 (-42.96%)
Mutual labels:  design-system, scss
Bootstrap 4 Sass Gulp 4 Boilerplate
A Bootstrap 4.5.2 boilerplate with font-awesome, sass, gulp 4 tasks
Stars: ✭ 103 (-23.7%)
Mutual labels:  gulp, scss
Nandomoreira Jekyll Theme
💎 My old website in Jekyll and Gulpjs
Stars: ✭ 101 (-25.19%)
Mutual labels:  gulp, jekyll
Css
The CSS design system that powers GitHub
Stars: ✭ 10,670 (+7803.7%)
Mutual labels:  design-system, scss
So Simple Theme
A simple Jekyll theme for words and pictures.
Stars: ✭ 1,701 (+1160%)
Mutual labels:  jekyll, scss
Css Flags
A collection of pure CSS flags, all single divs.
Stars: ✭ 90 (-33.33%)
Mutual labels:  gulp, scss
A11y.css
This CSS file intends to warn developers about possible risks and mistakes that exist in HTML code. It can also be used to roughly evaluate a site's quality by simply including it as an external stylesheet.
Stars: ✭ 1,277 (+845.93%)
Mutual labels:  documentation, scss
Cyber.dhs.gov
A site for CISA directives
Stars: ✭ 98 (-27.41%)
Mutual labels:  jekyll, scss
Garth
🥁 A really basic theme for Jekyll
Stars: ✭ 85 (-37.04%)
Mutual labels:  jekyll, scss
Design System
Design system for new Proton project
Stars: ✭ 101 (-25.19%)
Mutual labels:  design-system, scss
Frasco
Quick starter for Jekyll including full setup for Sass, PostCSS, Autoprefixer, stylelint, Webpack, ESLint, imagemin, Browsersync, etc.
Stars: ✭ 123 (-8.89%)
Mutual labels:  jekyll, scss
Baseguide
Lightweight and robust CSS framework for prototyping and production code.
Stars: ✭ 127 (-5.93%)
Mutual labels:  gulp, scss
Gaohaoyang.github.io
blog & blog theme🤘
Stars: ✭ 1,699 (+1158.52%)
Mutual labels:  jekyll, scss
Minimalism
Minimalism is a Jekyll theme for minimalist!
Stars: ✭ 74 (-45.19%)
Mutual labels:  jekyll, scss

U.S. Web Design System documentation

This repo includes code and documentation for the U.S. Web Design System website. For information on USWDS (components) themselves, please visit our uswds Github repo.

Note that this README includes steps to pull the latest version of USWDS into your local instance of the documentation.

Running locally

The U.S. Web Design System documentation is built using Jekyll for the file framework, gulp for task management, and the node module for USWDS.

Before you start

Recommended before install:

  1. Ruby Version Manager - RVM Installation guides
  2. Node Version Manager - NVM Installation guides

You will need to have the following installed on your machine before following the commands below:

  1. Ruby v2.2.2+, Installation guides
  2. Node v4.2.3+, Installation guides
  3. Bundler v1.12.3+, Installation guides
  4. Chrome v59 or higher (v60 if on Windows)
  5. Python v2.7* (For node-gyp dependency)

* If you're running into node-gyp issues on npm install you'll need to install python v2.7, which is the recommended version as of [email protected]. Once installed you can reference it via npm config set python /usr/bin/python2.7 or wherever you have installed. You can find that with whereis python command.

Building the documentation with gulp

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:

npm install

Now that all of your dependencies are installed, you can run your local server by running the following command:

npm 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 USWDS node module and the root level asset folders in this repo.

  • npm start -- --incremental or npm run serve: Runs your local server with incremental regeneration enabled to greatly improve build time. Use instead of npm start.

Using the latest version of the uswds package

Sometimes you will want to use the latest version of the uswds repo. Follow these steps to do so:

  1. Clone the latest version of the uswds repo.
  2. Run npm install to install the dependencies required for the package in the uswds directory.
  3. Run npm run build to create the built version of USWDS in the uswds directory.
  4. Run npm link in the root level of the uswds directory on your local machine.
  5. Run npm link uswds in the root level of the uswds-site directory on your local machine.
  6. Run npm start in the uswds directory, and make a note of the Local URL that Fractal is serving.
  7. In another terminal window, set the FRACTAL_BASE_URL env var to the running Fractal instance for uswds. In your terminal window in the uswds-site directory, enter export FRACTAL_BASE_URL="http://127.0.0.1:3000" (or the Local URL noted above).
  8. In the uswds-site window, run npm run serve in the uswds-site directory to start the Jekyll server.
  9. Run npm run watch in the uswds-site directory to have changes to that repo automatically built and compiled. Note: uswds-site will not automatically rebuild when there are changes in uswds, you'll need to trigger a site rebuild manually to reflect changes in the uswds repo.

You are now linked and using the local version of USWDS. To unlink this version, type npm unlink uswds from the root level of the uswds directory.

Fractal components

USWDS 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.

Deployment and previews

This site is deployed on Federalist, which automatically builds the public site whenever commits are pushed to main. Federalist also builds public previews for each branch pushed to GitHub.

Updating the USWDS version

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.:

npm install --save "uswds/uswds#fb49e4f"

Alternatively, to use a specific version tag, use e.g.:

npm 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 main branch commits--otherwise a commit hash will show up as the version on the production site, which would be confusing.

Adding content to the "Updates" section

See the _posts directory for instructions on adding updates.

Dynamic content

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:

rm -rf .jekyll_get_cache

Contributing

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.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].