This is the 11ty Cloud.gov Pages static site generator for the homepage and help content for .gov. The code for the .gov registrar is at cisagov/getgov.
This is built using an 11ty static site generator (SSG) template with U.S. Web Design System v 3.0 (USWDS) and is run as a Cloud.gov Pages website.
The template this is built on strives to be compliant with requirements set by 21st Century IDEA Act. The standards require that a website or digital service:
- is accessible to individuals with disabilities;
- has a consistent appearance;
- does not duplicate any legacy websites (the legislation also requires agencies to ensure that legacy websites are regularly reviewed, removed, and consolidated);
- has a search function;
- uses an industry standard secure connection;
- “is designed around user needs with data-driven analysis influencing management and development decisions, using qualitative and quantitative data to determine user goals, needs, and behaviors, and continually test the website, web-based form, web-based application, or digital service to ensure that user needs are addressed;”
- allows for user customization; and
- is mobile-friendly.
For more about the template and it's functionality see here.
npm install
npm run dev
If you are having issues with assets being locally cached/not updating:
npm run clean && npm run dev
npm run pa11y
You can create new pages by creating a new markdown file (.md) and adding “front matter” to the top of the markdown file. The front matter section starts and ends with three hyphens (---). It consists of key-value pairs that define some meta-data and options for the page. You should set the following front matter on all pages.
title:
The title of the page will be displayed as an H1 tag on the page.
Example: title: Before you request a .gov domain
permalink:
Determines the portion of the url that will follow www.get.gov/
Example: permalinks: /domains/benefits/ means this page will be found at www.get.gov/domains/benefits/
layout:
Sets the layout this page will use. All layouts are stored in the /layouts/ folder, and the value for layout should include a reference to that folder.
Example: layout: layouts/info-page
The following layouts have been customized for get.gov.
layout: layouts/landing
Landing pages that serve as an index to other pages use the landing layout.
layout: layouts/info-page
Pages within a collection that focus on presenting information about a particular topic use the info-page layout.
layout: layouts/post
Blog posts use the post layout.
excerpt:
Sets the short description about this page or post that will be displayed on the landing page. This meta-data isn’t necessary on landing pages, but is required on detailed information pages and blog posts.
Example: excerpt: Follow these steps to complete your request as quickly as possible
tags:
Determines which “collection” this page or post belongs to. Pages within the same collection will be listed on the collection’s landing page, as well as in the sidenav. All blog posts use the post tag, which is listed first. Additional tags for a blog post will be displayed as a “topic” tag that represents the topic this and related posts cover.
Example for an info page: tags: domains
Example for a blog post: tags: post topic1 topic2
eleventyNavigation:
This sets options for the eleventyNavigation plugin which is used for organizing the sidenav. The value for this key is a set of additional (child) key-value pairs
key:
Determines which collection this page should be grouped with in the navigation
order:
Determines in which order position this page should be displayed on the landing page and in the sidenav. The order is ascending. A page with order: 2 is listed before a page with order order: 9.
title:
Determines the title of the page in the sidenav. While typically this would be exactly the same as the page title, it allows for flexibility to display shorter names in the sidenav.
Example:
eleventyNavigation:
key: domains
order: 2
title: Before you request a .gov domain
In addition, there are front matter options that are used on some but not all pages, in accordance with the design of the page. For all front matter that provides a binary option, if you don’t want to use the option (i.e. you don’t want it to set the value to true), you can either set it to false or simply omit this piece of front matter.
sidenav:
Determines if a left-hand side navigation will be included on the page. This navigation will include all pages that are within the same collection (i.e. share the same tag).
outlined_links:
Provides a binary option to wrap the links on the landing page in an outline. This style is currently used for the “Domains” page.
hide_nav_search
Provides a binary option to hide the search bar in the navigation. This is used on pages that have a large search box, such as the help page and the search results.
Example: hide_nav_search: true
searchbox:
Provides a binary option to display a large search box in the page’s heading below the title. Currently used on the help landing page. Note that if you include the search box on the page, you likely want to set hide_nav_search: true.
Example: searchbox: true
For preview links generated on the platform, we automatically set the pathPrefix in the .eleventy.js file base on the BASEURL environment variable. We use the built-in 11ty filter for url to properly append the prefix path for the linked page. When adding new links, use the following syntax:
<a href="{{ '/myDir/' | url }}">Link to My Dir</a>See the 11ty docs
All of your images will be stored in the _img/ directory. To reference your images in your templates you can use the shortcodes built into the template.
For referencing an image without a style class, you will pass the template shortcode the image's source path and the alternative image name in that order. ie:
{% image "_img/my-image.png" "My PNG Image Alternative Name" %}
For referencing an image with a style class, you will pass the template shortcode the image's source path, class names, and the alternative image name in that order. ie:
{% image_with_class "_img/my-image.png" "img-class another-class" "My PNG Image Alternative Name" %}
USWDS has sprite icons available for use. Here is the list of icons available when using the sprite shortcode uswds_icon in the template. The following example is how you can reference the icon in a template.
{% uswds_icon "<USWDS sprite name>" %}
CSS and SASS can be added or imported into the styles/styles.scss. You can also use USWDS Design Tokens in the styles/themes files to update colors, fonts, and layout to fit your site's branding. This template uses esbuildand autoprefixer to bundle your SASS/CSS and fingerprint the files in the site build.
Javascript can be added to the admin UI or site UI by adding or importing code into the js/admin.js or js/app.js files respectively. This template uses esbuild to bundle your javascript and fingerprint the files in the site build.
Environment variables are set and managed on pages.cloud.gov
See CONTRIBUTING for additional information.
This project is in the worldwide public domain. As stated in CONTRIBUTING:
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.