- 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 cloud.pages.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. |
A tool for managing the digital.gov editorial workflow on GitHub. | |
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 v3.0 - the design system used in digital.gov.
- Gulp - the asset pipeline.
Unix-based systems are recommended for development. If you are using Windows, consider using the Windows Subsystem for Linux to run a Unix-based system on your machine.
If you do not have a Unix-based system, you will recieve additional linting errors when running the npm run lint
commands.
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 v18. 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.123.3. 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:
- Uninstall the current version with
brew uninstall hugo
- Visit https://github.com/Homebrew/homebrew-core/blob/master/Formula/h/hugo.rb
- Click the “History” link
- Find the “bottle” commit for the desired version (Ex: 'hugo: update 0.123.3' bottle)
- Press the “View at this point in history” button
- Press the “Raw” button
- Right-click anywhere on the page and choose “Save as…”
- Save hugo.rb to any directory (home, downloads, etc.)
- Open a terminal
- CD into the directory where you saved the hugo.rb file
- Install with
brew install hugo.rb
- Prevent automatic updates with
brew pin hugo
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:
npm start
NPM will run the following scripts:
gulp env
— sets the environment variable to development (local builds only, not in Federalist)gulp
— builds and compresses all of the SCSS and JS files, and copies jquery and uswds js fromnode_modules
and puts them in the/dist/
folder.gulp watch
— starts a watch task to look for changes in the SCSS and JS fileshugo serve
— builds all of the pages in hugo and creates a local server athttp://localhost:1313/
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 Gulp tasks 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.
NOTE: This is now included in the npm start
command above
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
— builds all the pages in the site, without creating a serverhugo serve
— builds all of the pages in hugo and creates a local server athttp://localhost:1313/
hugo serve --templateMetricsHints
— for seeing where you can apply caching in templates and speed up the build time See more in the Hugo docs »
- Read through the recent releases
- Run
brew upgrade hugo
to upgrade your local copy (docs). - Set the version in the
.hugo-version
file. This is only used for telling Federalist which version of Hugo they should checkout and use. - Update this README.md to show the current hugo version
- Update the version in `.circleci/config.yml to ensure that the same version of Hugo is being used for CI.
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.
Warning Site must be running locally to perform the scan.
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
Install
andRun
instructions above. - In a separate terminal window, run
npm run test:pa11y
to initiate the accessibility checker.
Accessibility testing configuration is located in the .pa11yci file.
To test the validity of API JSON files, run npm run lint:json
in the terminal on your local machine. This will check the validity of the Hugo generated JSON files used for the API. Currently, it validates authors, images, and topics using the tool jsonlint
. If an issue is found with the JSON, jsonlint
will return a non-zero exit code causing CircleCI to fail. See the wiki API page for fixing API issues.
Markdown testing can be performed by running npm run lint:markdown
. The rules that are used for the linter can be found in .markdown-lint.yml
.
HTML linting can be performed by running 'npm run test:htmlproofer'. To have HTMLproofer ignore certain content see: https://github.com/gjtorikian/html-proofer#ignoring-content
{{< 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
- Communities of Practice Job Board