digitalgov.gov: An HTML repository from jimkreft

We help people in government build better digital services

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 »

Repositories

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.
GSA/digitalgov-workflow (archived)	A tool for managing the digital.gov editorial workflow on GitHub.
GSA/redir (archived)	A basic Jekyll template to use for temporary redirects.

Development Guide

Technologies you should be familiarize yourself with

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.

Installation

Prerequisites

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.

Install Hugo 0.123.3

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

Setup

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!

Local Development

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 from node_modules and puts them in the /dist/ folder.
gulp watch — starts a watch task to look for changes in the SCSS and JS files
hugo serve — builds all of the pages in hugo and creates a local server at http://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

Configuration

Environment Variables

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.

Asset Pipeline

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

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 build — builds all the pages in the site, without creating a server
hugo serve — builds all of the pages in hugo and creates a local server at http://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 »

Upgrading Hugo

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.

Accessibility tests

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.

Running tests

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 and Run 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.

Linters

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

Common Regex scripts

convert legacy-img to standard img

{{< legacy-img src="/\d+/\d+/\d{2,4}[-x]+\d{2,4}[_-]*(.+?)\.[pngje]+"(
alt=".+?")* >}}

{{< img src="$1"$2 >}}

convert CDN links

{{< legacy-img src="/(\d{4,4}) {{< legacy-img src="$1

replace `url` with `slug` in posts

^url: .+/([^/]+)\.md
slug: $1

jimkreft/digitalgov.gov