Getting started with Jekyll
Welcome! The intended audience of this guide is content creators who have limited technical knowledge and no HTML, CSS, or YAML experience. Keep in mind that each template and theme is a little different. If you get stuck, don’t hesitate to reach out.
Federalist monitors your site’s GitHub repository (or repo) for changes you make. It will automatically build a new version of your site in a few minutes. You can view the live site from Federalist and clicking “View site”.
If you’re unfamiliar with GitHub, the Federalist team recommends that you familiarize yourself before continuing through this guide.
Getting Started with Jekyll
Immediately after building a new site, you need to customize the general content
on your site, including your site title and office’s contact information. To do
that, you’ll need to edit the configuration options in
_config.yml. Keep in
mind that this file is a special file type called “YAML” that requires specific
formatting. Indentation is important to keep related options together — in order
for Jekyll to successfully read the configuration file so that the site will
build with the proper settings, the correct indentation must be used. We
recommend using space characters instead of tabs for nesting configuration
options. Learn more about working with YAML.
Here’s an example
# This is a YAML comment. A comment starts # with the # character. Comments are # ignored by Federalist. title: This is the site title theme: uswds-jekyll site_width: wide # GitHub information # This is used for adding an edit this page link # to the footer github: organization: 18F repository: federalist-uswds-template default_branch: report-config # Notice how two space characters are used to # indent the properties. This means they are # all children of the “github” property.
Your content lives in the pages/ directory. Click the pages/ directory in GitHub to see your existing pages. Select “page.md” from the list of options. Once you’re on page.md, look for the pencil icon near the top right of the content window to edit the page.
The three dashes
--- separate the “front matter” of the page from the content
of the page. Front matter is used to instruct the build system about how to
build the page and provide additional data. Learn more about
--- # This is front matter. title: Title of your page --- Content for your page goes here.
The content of your page starts below the second set of three dashes
end the front matter section. The content is all in markdown format,
a plain-text simple markup language
designed to be readable for content editors. Try editing your heading by
replacing the text “Welcome to the Federalist Report Template” with “Hello
world!”. Learn more about Markdown.
Once you’re finished making content changes, scroll to the bottom of the page and click “Commit changes.” Federalist will automatically detect your changes and start building your site. It should be live within a few minutes.
When making a commit, it’s best to describe the change in GitHub’s commit summary, along with why you’re making the change in the commit description. This helps members of your team understand the motivation behind the changes you’ve made when looking back on the repo’s history.
Once your change is committed, Federalist will start rebuilding your site. You can see the build progress on the build history page.
Agency logo and other assets
Images, PDFs, and other static files served with your site are called “assets”. We recommend they be stored in the assets/ directory.
There’s no standard practice, but many projects group similar assets into
assets/images for images or
assets/css for CSS files.
Go to the assets/ directory on GitHub. Then click “Upload files”. This will
allow you to upload files like your agency logo to your repo. You’ll then be
able to reference the asset by using a path like
your content and in
Create a new page
Click the pages/ directory in GitHub, then click the “Create new file” button.
Give the file a name with an
The filename should be relatively short and use only lowercase
letters, numbers, dashes, and underscores. Federalist will use this filename in
the page’s URL by default, so keeping your URLs short and consistent will make
them easier to read and remember.
open-source-policy.md is a great filename
for a page containing your agency’s open source policy.
You’ll want to include some basic front matter. Copy and paste this example to start:
--- title: "Your new content page" layout: page permalink: /link/to/your-new-content-page/ --- ## Your new content page heading And your content goes here.
title is the title of your page.
layout specifies which layout to use. This
page, meaning that your content is going to be put onto the default
“page” HTML layout.
permalink is the URL to your new page. Don’t forget to
commit your changes when you’re done.
Some templates are geared toward a specific task, like the Basic Report template, which features a downloadable PDF report. You’ll want to refer to the template specific documentation to learn how to configure your template beyond what is covered in this guide.
Once you’ve got the basics down, we recommend that you check out our customization guide for some more details on how to customize your site.