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.

Https

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.

How Builds Work

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, then uploads your site files to S3. 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 an existing repository, you specify a default branch of your repository to serve as the “production” version of the site and choose your build engine.

Static Site Engine Options

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.

When building our your sites, please remember that all government websites must meet section 508 accessibility standards. 18F provides guidance for building accessible websites.

Jekyll resources

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 our templates.

Jekyll build features

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.

Configuration

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.

Metadata defaults

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.

Base URLs

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 federalist.18f.gov/preview/18f/hub/new-draft, where /preview/18f/hub is the baseurl.

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:

Link: [About Us]({{site.baseurl}}/about-us)

Image: ![18F]({{site.baseurl}}/uploads/18f-logo.png)

Conditionally set robots

To instruct search engines not to index the preview builds of your site, try adding the following code within your site’s <head> tags which are most likely found in your template’s head.html or meta.html file:

{% unless site.branch == "master" %}
  <meta name="robots" content="noindex, nofollow">
{% endunless %}

Note: This code sample assumes the live version of your site’s code is maintained in the master branch of your site’s code repository.

For all versions of your site that aren’t built from master, the source code of the site will contain the code above. For an example, see here, view source, and jump to line 57.

Jekyll Plugins

Jekyll has a plugin system for adding custom features to the build process of your website. Use-cases for plugins include automatically generating new pages or templates, fetching data or content from external resources, and CCS or JavaScript compilation. Learn more about Jekyll plugins.

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 ruby, python, and node.js. You can write plugins that take advantage of these without needing a Gemfile.

To see the exact configuration of the build environment, see the build environment Dockerfile.

Note: using Gemfile may considerably slow down the generation of your website, depending on how long the bundle install step takes to complete.

Hugo (experimental)

Federalist can also generate websites with Hugo, the Go-based static site generator. See the Hugo Docs for getting started with Hugo.

Hugo version

When building a Federalist site using Hugo, the desired version of Hugo for building your site must be specified in a .hugo-verson file located in your repository’s root directory.

Sample .hugo-version file contents:

0.48

Build environment variables

At the time your site is built with either Jekyll or Hugo, a number of special environment variables are exposed. You can access these environment variables with your build engine to customize your build (for instance, to add some special text to your site to show which branch has been built).

See the federalist-garden-build README for information on the environment variables that your site build can access.