This is an 11ty static site generator (SSG) template using U.S. Web Design System v 3.0 (USWDS) and is focused on providing developers a starter template and reference implementation for Federalist/Cloud.gov Pages websites.
This project 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.
This repository contains the following examples and functionality:
✅ Publish blog posts, press releases, announcements, etc. To modify this code, check out blog/index.html
, which manages how the posts are listed. You should then check out _includes/layouts/post.html
to see how individual posts are structured.
✅ Publish single one-off pages. Instead of creating lots of folders throughout the root directory, you should put single pages in pages
folder and change the permalink
at the top of each page. Use sub-folders only when you really need to.
✅ There are two different kinds of pages
, one does not have a side bar navigation, and the other uses _includes/sidenav.html
. You can enable this option by adding sidenav: true
to your page front matter.
---
title: Document with Sidenav
layout: layout/page
sidenav: true
permalink: /document-with-sidenav
---
✅ Search.gov integration - Once you have registered and configured Search.gov for your site by following these instructions, add your "affiliate" and "access key" to _data/site.yml
. Ex.
searchgov:
# You should not change this.
endpoint: https://search.usa.gov
# replace this with your search.gov account
affiliate: federalist-uswds-example
# replace with your access key
access_key: xX1gtb2RcnLbIYkHAcB6IaTRr4ZfN-p16ofcyUebeko=
# this renders the results within the page instead of sending to user to search.gov
inline: true
The logic for using Search.gov can be found in _includes/searchgov/form.html
and supports displaying the results inline or sending the user to Search.gov the view the results. This setting defaults to "inline" but can be changed by setting
searchgov:
inline: false
in _data/site.yml
.
✅ Digital Analytics Program (DAP) integration - Once you have registered your site with DAP add your "agency" and optionally, subagency
to _data/site.yml
and uncomment the appropriate lines. Ex.
dap:
# agency: your-agency
# Optional
# subagency: your-subagency
✅ Google Analytics integration - If you have a Google Analytics account to use, add your "ua" to _data/site.yml
and uncomment the appropriate lines. Ex.
ga:
# ua: your-ua
npm install
TODO
npm run dev
TODO
The Netlify CMS can be configured in /admin/config.yml
and you will update the
repo
key to be your Github organization and repository name.
backend:
name: github
repo: <your-github-org>/<your-repository-name>
base_url: https://federalistapp.18f.gov
auth_endpoint: external/auth/github
preview_context: federalist/build
branch: master
use_graphql: true
You can run the Netlify CMS locally to more easily customize and troubleshoot the CMS to you content.
We provide comments in the /admin/config.yml
instructing you how to change the backend
values from your production site to the local development.
*Note: Make sure to not commit and push the config with the
backend
set for local develop to Github or else you will break your production site's Netlify CMS.
# Local development backend
backend:
name: git-gateway
local_backend: true
Once you /admin/config.yml
is set to local development, you run npm run dev:cms
to
serve as a development authentication server.
TODO
TODO
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.
TODO
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.