Federalist is a continuous deployment-like build environment for static sites. It works by setting a webhook on your site's GitHub repository and generates your site on each
push event to that repository. Changes made to the site's content and files in its repository through the GitHub web editor or otherwise launch rebuild tasks of the site in a build environment container.
If you don't want to use the Federalist templates, you can add your own GitHub repository to build a completely custom site. When you add a repository-based site, you can choose your build engine: Jekyll, Hugo (not yet implemented), or static, which simply pushes the files in your repository. You can also specify a default branch of your repository to serve as the "production" version of the site.
Federalist is designed to be a modular service. Some people customize their sites by creating new templates. Others use a default template content, editing with GitHub. When used this way Federalist acts a no-configuration, production-ready hosting solution for GitHub-based static websites, hosted using cloud.gov tooling, with a custom domain.
Build engine resources
All government websites must meet section 508 accessibility standards. 18F provides guidance for building accessible websites.
Federalist can generate any Jekyll website, which lets you build custom websites hosted on Federalist. For documentation on getting started with Jekyll, see jekyllrb.com.
For an example of a Jekyll site optimized for Federalist, see the federalist-modern-team-template.
Hugo resources (experimental)
Federalist provides features beyond just generating Jekyll sites. The steps below outline how to set up custom websites that best take advantage of these features.
Federalist adds a
site.branch attribute to your global site object with the value of the current branch name. You can access this value in your templates and content and use it to style builds based on the working branch.
If you specify front-matter defaults in your Jekyll site configuration, Federalist will pre-fill the front-matter of a new post with these defaults.
To handle routing sites for previews, Federalist automatically sets a
baseurl path for your site. This essentially nests your site in a subdirectory under the
federalist.18f.gov domain, such as
/preview/18f/hub is the
All links to other pages or resources on the site require a
baseurl prefix. If you're designing a custom template to work with Federalist, make sure all references to relative links include
site.baseurl prefixes, including trailing slashes, as follows:
Federalist supports Jekyll plugins, enabling any plugins in a site's
_plugins directory. If the site includes a
Gemfile, Federalist will also run
bundle install && bundle exec jekyll build to install required Ruby gems and generate the site with those libraries available for use in plugins. You can also use a
Gemfile to change the version of Jekyll used to build the site.
Several dependencies are already available for use in the building environment. These include
node.js, as well as the
github-pages gem, which includes several common gems used for building sites. You can write plugins that take advantage of these without needing a
Gemfile may considerably slow down the generation of your website, depending on how long the
bundle install step takes to complete.