- Sign-up for the Digital.gov newsletter »
- Follow us on Twitter »
- Like our page on Facebook »
Want to learn more about how we work? Check out our Wiki page »
As a product, digital.gov maintains a collection of repositories. All of our work is open source and we encourage you to take a look at and contribute to our projects by submitting a Pull Request, a Github Issue, or commenting on existing Issues and Pull Requests.
The repositories below are all used to maintain digital.gov:
Platform
| Project | Description |
|---|---|
| GSA/digitalgov.gov | (This repo) Site platform currently deployed as a static site built with Hugo and hosted by Federalist and Cloud.gov. |
| 18F/dns | DNS configuration for digital.gov domains managed by GSA TTS. |
| uswds/uswds | This site is developed using the U.S. Web Design System v2, managed by GSA TTS. |
Tools - projects we have created in order to better aid our work on the digital.gov platform.
| Project | Description |
|---|---|
| GSA/digital.gov-design | A collection of design assets used for the digital.gov platform. |
| GSA/digitalgov-workflow | A tool for managing the digital.gov editorial workflow on GitHub. |
| GSA/redir | A basic Jekyll template to use for temporary redirects. |
- Hugo - The primary site engine that builds digital.gov code and content.
- Front Matter - The top of each page/post includes keywords within
---tags. This is meta data that helps Hugo build the site, but you can also use it to pass custom variables. - U.S. Web Design System v 2.0 - the design system used in digital.gov.
- Gulp - the asset pipeline.
Install Gulp globally from your terminal command line:
npm install gulp-cli -g
To use Gulp, you must have Node and NPM installed.
We're currently using Node v10.16.3. A recommended way of changing your Node version is to use a node version manager tool like n to quickly change between node versions.
NPM is package along with Node. Check your versions of these in your terminal command line by typing:
node -v
npm -v
Using Homebrew is a quick and easy way to install Hugo. Install Homebrew before getting started.
Read the HUGO quickstart guide »
For OSX:
brew install hugo
see https://gohugo.io/getting-started/installing/ for other OSs
Quickly check your Hugo version at your terminal command line by running:
hugo version
Note: Digital.gov currently uses Hugo version 0.66.0. This is noted in our .hugo-version file. If Hugo has released a new version, but digital.gov hasn't been upgraded to that version, you may get errors when building locally. It is possible to use Homebrew to download a previous version of Hugo. To do that follow these instructions: Using Legecy Versions of the Hugo Static Site Generator
Once the prerequisites are installed, clone the repository to your local machine. Then navigate to the project folder in your terminal and run:
npm install
This will install all of the Node dependencies needed to run your Hugo environment. This may take a little while!
Running the local development server is as simple as running:
hugo serve
When Hugo is done building, you should see a success message like:
Web Server is available at //localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
You may then view your local site in the browser at `http://localhost:1313/'.
Local development is powered by BrowserSync, to allow rapid development through:
- A local development server at
http://localhost:1313/. - Automatic CSS & JS updates without reloading the page
- Automatic page reloads when content is changed
This project uses environment variables to handle uploading of images to AWS (powered by Gulp scripts).
In your command line terminal run cp env.example .env to create a template .env file in the root directory of the project.
Replace “[your key goes here]” in the .env file with your AWS key.
All style and image build tasks are handled by Gulp and are located in gulpfile.js. All parts of the build are configurable in discrete files (located in config/gulp) to make management easy.
Starting the gulp watch tasks to compile styles. This can be done in the terminal command line by running:
gulp
You would want to have the Hugo build running along with a gulp session in separate terminal sessions in order to compile and watch both content and style changes.
Tip: Use the keyboard shortcut control + c to stop the gulp watch process.
Images found in content/images/inbox/ will be optimized and compressed and sent to an AWS S3 bucket for usage in your layouts and content. This is done by running the gulp img command. See the digital.gov wiki for how to process images.
Other helpful HUGO commands:
hugo serve --templateMetricsHints— for seeing where you can apply caching in templates and speed up the build time See more »
- Read through the recent releases
- Run
brew upgrade hugoto upgrade your local copy (docs). - Set the version in the
.hugo-versionfile. This is only used for telling Federalist which version of Hugo they should checkout and use.
We follow the WCAG2AA standard, and one of the ways we check that we're following the right rules is through automated tools, like pa11y. For more info on the rules being tested checkout the pa11y wiki.
To run a web accessibility test on digital.gov do the following:
- Check out the site from GitHub https://github.com/GSA/digitalgov.gov/
- Install and run the site locally following the
InstallandRuninstructions above. Site must be running locally to perform the scan.
- If this is your first time running pa11y, then you'll need to run
npm installto make sure pa11ly is installed.
- In a separate terminal window, run
npm run test:pa11yto initiate the accessibility checker.
Note: Currently, this only runs accessiblity checks on the site home page as a Proof of Concept demonstration.
Accessibility testing configuration is located in the .pa11yci file.
{{< legacy-img src="/\d+/\d+/\d{2,4}[-x]+\d{2,4}[_-]*(.+?)\.[pngje]+"( alt=".+?")* >}}
{{< img src="$1"$2 >}}
{{< legacy-img src="/(\d{4,4})
{{< legacy-img src="$1
^url: .+/([^/]+)\.md
slug: $1