Skip to content
DEPRECATED: 18F Guides Template style elements, derived from CFPB/DOCter
CSS Ruby HTML JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
_sass Merge branch 'master' into dw-linkstyle Oct 27, 2017
test fix tests Oct 27, 2017
.gitignore change the tooltip for private links to be 18F-specific Mar 31, 2016
Gemfile Initial commit Aug 17, 2015
package.json use USWDS; wip rethemeing Mar 29, 2017

guides_style_18f: 18F Guides style gem


Provides consistent style elements for Jekyll-based web sites based on the 18F Guides Template. The 18F Guides theme is based on DOCter from CFPB.


In your Gemfile, include the following:

group :jekyll_plugins do
  gem 'guides_style_18f'

Add an assets/css/styles.scss file that contains at least the following:


@import "guides_style_18f";

Then in your _config.yml file, add the following (you may need to remove any layout: front matter from existing pages for this to take effect):

theme: guides_style_18f

      path: ""
      layout: default

Build the site per usual, and observe the results.

Additional features

Here are some other features that can be enabled via _config.yml:

# To use the shared 18F Guides Teamplate assets when deploying to
#, to avoid having to rebuild the site for minor style and
# script updates:
asset_root: /guides-template

# This adds the "back to" breadcrumb link under the page title:
  url: ""
  text: Read more 18F Guides

# If you use Analytics, add your code here:
google_analytics_ua: UA-????????-??

# If you want all of the navigation bar entries expanded by default, add this
# property and it to true:
expand_nav: true

Additional scripts and styles

If you'd like to add additional scripts or styles to every page on the site, you can add styles: and scripts: lists to _config.yml. To add them to a particular page, add these lists to the page's front matter.

Alternate navigation bar titles

If you want a page to have a different title in the navigation bar than that of the page itself, add a navtitle: property to the page's front matter:

title: Since brevity is the soul of wit, I'll be brief.
navtitle: Polonius's advice

Selectively expanding navigation bar items

If you wish to expand or contract specific navigation bar items, add the expand_nav: property to those items in the navigation: list in _config.yml. For example, the Update the config file entry will expand since the default expand_nav property is true, but Add a new page will remain collapsed:

expand_nav: true

- text: Introduction
  internal: true
- text: Add a new page
  url: add-a-new-page/
  internal: true
  expand_nav: false
  - text: Make a child page
    url: make-a-child-page/
    internal: true
- text: Update the config file
  url: update-the-config-file/
  internal: true
  - text: Understanding the `baseurl:` property
    url: understanding-baseurl/
    internal: true


There are two options for search.



  • Generates a search index locally, which has the advantage of being self-contained. This means you can easily test search locally, on a staging site, etc.
  • Search results are shown in your site's layout


  • Slows down your build

Usage: see the instructions.


  • A hosted service, so your site has fewer moving parts.
  • A more full-featured search engine
  • Search results show a preview of the text on the page, with highlighted term(s)
  • Provides analytics


  • You need to register your site
  • Can't test search results locally


  1. Register your site at

  2. Add the following to your _config.yml:

    search_gov_handle: <your Site Handle from the Settings page>


First, choose a Jekyll site you'd like to use to view the impact of your updates and clone its repository; then clone this repository into the same parent directory. For example, to use the 18F Guides Template:

$ git clone
$ git clone

In the Gemfile of the Jekyll site's repository, include the following:

group :jekyll_plugins do
  gem 'guides_style_18f', :path => '../guides-style'

then build the site with bundle exec jekyll serve. You can find the different style assets and templates within subdirectories of the assets and lib/guides_style_18f directories of this repository. Edit those, then rebuild the Jekyll site as usual to see the results.

Public domain

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.

You can’t perform that action at this time.