Federalist is becoming cloud.gov logo icon cloud.gov Pages! Checkout more about the transition here. 🎉

Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.


The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Customizing Your Site

Customizing your site


This page describes some more advanced features of Federalist and introduces Jekyll, one of the technologies behind Federalist.

You may have realized that Federalist is based on several technologies. One of the most important is Jekyll, a site generator. Federalist uses Jekyll to build your site, so anything you can do with Jekyll, you can do with Federalist. If you understand how Jekyll works, you can customize all aspects of your entire site.

The Federalist templates are all configured to use a theme which houses all the HTML, CSS, and other web assets for your site. You can override everything on a per-file basis by including your own version of the file in your repo. Learn more about Jekyll themes.

Layouts and includes

Instead of complete HTML files, Jekyll uses the Liquid templating language to compile multiple layouts and includes. A layout is a container for your page that typically contains the most common elements across your pages, like the site header and footer. The layout is specified in the page’s front matter. Includes are HTML snippets or partials that allow you to reuse them across your site. A common include could be a UI component or a side navigation that is reused across the site. Learn more about Jekyll includes.


Assets are things like images, PDFs, CSS, and JavaScript files that are served with your site. The theme will house many of them. These can also be overridden in your repo by including your own version under the same file path.


You can use CSS with Jekyll just like any other static asset. However, one of Jekyll’s most powerful features is how it uses Sass to make writing CSS easier. Sass files use the scss file extension. Your main scss file should live under the assets/ directory. Learn more about Sass.


When you include an scss file under the assets/ directory, Jekyll will only process it as Sass if you include the front matter marker (three dashes ---).

Best practice

Sass files under _sass/ can be imported by using the @import syntax in your main scss file. You can use this to organize individual UI component styles with individual scss files, and then import them from an assets/site.scss file.

U.S. Web Design System

The U.S. Web Design System (USWDS) is a design system for the federal government backed by user research to design and build fast, accessible, mobile-friendly government websites.

The USWDS is written in Sass, which is compiled by Jekyll to CSS. It is designed to be configurable, so you can make customizations by overriding variables or including additional CSS rules. Learn more about customizing the U.S. Web Design System.

Advanced customization

The Federalist themes are meant to keep things simpler for you, the site owner. To do this, the theme makes some assumptions on your behalf. Think of Federalist themes as training wheels or guide rails. If you are making a lot of customizations and overrides, the theme might be more burdensome than it is helpful. That is okay! At this point, you probably want to remove the theme and take full control over your website by copying all the theme files into your repo and removing the theme from _config.yml and your Gemfile. This process is described in Jekyll’s documentation on converting to a regular theme.

Federalist would also like to learn more about how the theme is or is not working for you. Please email us describing your experience so we can learn from you. Thank you!

Custom 404 pages

If a user navigates to a page on your site that does not exist, they will see a “404 Page” (webspeak for a page that doesn’t exist). Federalist provides a default 404 Page (shown below), but you may prefer something that looks and feels like it is part of your site.

Federalist default 404 page

Default 404 Page

In order to use a custom 404 Page, name your 404 Page “404.html” and make sure it is at the root of and included in the resources that are deployed. Jekyll sites should also have the file in the root of the project with the front matter data value set to permalink: /404.html, see the docs for reference. If you need to direct 404 errors to a file not named “404.html” to support single page applications (SPA), let #federalist-support or federalist-support@gsa.gov know that you would like to use a custom 404 page for a SPA and we will handle the rest.

If you have a custom domain and, while trying to set up your custom 404 page using a development branch, you are able to see it when running locally, but not live on the branch site, try pushing it to your custom domain.


Federalist supports the proposed security.txt standard. Simply create and place the security.txt file within the .well-known directory created at the root of your repository. Visit the security.txt website, for more information on this proposed standard.

[repository root]/.well-known/security.txt