This Jekyll theme is developed using the U.S. Web Design System v 2.0 and is focused on providing developers a starter kit and reference implementation for Federalist websites.
This code uses the Jekyll site engine and built with Ruby. If you prefer to use Javascript, check out federalist-uswds-gatsby, which uses Gatsby site engine.
This project strives to be compliant with requirements set by 21st Century IDEA Act. The standards require that a website or digital service:
Both start off looking very similar, but differ in what use cases they are best for. Are you:
use federalist-uswds-jekyll (this repository). If you:
use uswds-jekyll.
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 _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.
✅ Publish data (for example: job listings, links, references), you can use the template _layouts/data.html
. Just create a file in you _pages
folder with the following options:
---
title: Collections Page
layout: data
permalink: /collections
datafile: collections
---
The reference to datafile
referers to the name of the file in _data/collections.yml
and loops through the values. Feel free to modify this as needed.
✅ 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: 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 _config.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 _config.yml
.
✅ Digital Analytics Program (DAP) integration - Once you have registered your site with DAP add your "agency" and optionally, subagency
to _config.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 _config.yml
and uncomment the appropriate lines. Ex.
ga:
# ua: your-ua
Non-developers should focus on editing markdown content in the _posts
and _pages
folder
We try to keep configuration options to a minimum so you can easily change functionality. You should review _config.yml
to see the options that are available to you. There are a few values on top that you need to change. They refer to the agency name and contact information. The rest of _config.yml
has a range of more advanced options.
The assets/
folder stores your Javascript, CSS, images, and other media assets. Additional SASS partials should be added to the _sass/
folder where they can be imported. USWDS assets are automatically copied into the assets/
folder when running jekyll serve
or jekyll build
If you look at package.json
you will see that the npm run federalist
command that will run when running on the Federalist platform.
Do not edit files in the _site/
folder. These files are auto-generated, and any change you make in the folder will be overwritten.
To edit the look and feel of the site, you need to edit files in _includes/
folder, which render key components, like the menu, side navigation, and logos.
index.html
may not require much editing, depending on how you customize hero.html
and highlights.html
.
_layouts/
may require the least amount of editing of all the files since they are primarily responsible for printing the content.
blog/index.html
can be edited, but be careful. It will impact the pagination system for the posts. If you do edit the file, be prepared to edit _config.yml
. For example, you may need go change configurations for jekyll-paginate-v2
search/index.html
is used by search.gov.
This will create a copy of this repo in a Github repository of your choice and add it to your Federalist dashboard.
This will create a copy of this repo in a Github repository of your choice but you will need to add it your Federalist dashboard.
npx
(requires node)$ npx degit https://github.com/18F/federalist-uswds-jekyll#main <destination-folder>
$ cd <destination-folder>
$ git init
$ git symbolic-ref HEAD refs/heads/main
$ git add . && git commit -m 'Initial commit'
$ git remote add origin git@github.com:<your-org>/<your-repo>.git
(Make sure to replace `<your-org>` and `<your-repo>` above with the correct values)
$ git push -u origin main
$ git clone https://github.com/18F/federalist-uswds-jekyll
$ cd federalist-uswds-jekyll
node
and ruby
$ npm install
$ bundle install
$ npm start
OR
$ bundle exec jekyll serve
To build but not serve the site, run npm run build
or bundle exec jekyll build
.
$ docker-compose run node npm install
$ docker-compose build
$ docker-compose up
To build but not serve the site, run:
docker-compose run ruby bundle exec jekyll build
.
Note that when built by Federalist, npm run federalist
is used instead of
npm run build
.
Open your web browser to localhost:4000 to view your site.
node
and ruby
$ npm test
OR
$ bundle exec htmlproofer _site; npx a11y '_site/**/*.html'
$ docker-compose run ruby bundle exec htmlproofer _site; npx a11y '_site/**/*.html'
--
tags. This is meta data that helps Jekyll build the site, but you can also use it to pass custom variables.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.