18F Guides Template

Introduction

Use this template to create 18F Guides and other 18F-branded documentation available on 18F Pages. It's structured like an 18F Guides guide, and it walks you through the process of creating and publishing an 18F Pages document based on the same theme.

The template is derived from CFPB/DOCter. It uses Jekyll as the rendering engine.

Create a new guide/document

To get started on a new guide (or other document based on this theme), follow the "Getting started" instructions in the 18F/guides-template GitHub repository to create a local clone of this template.

Once you've created a clone, click the Add a New Page entry in the table of contents to begin the rest of the steps.

Update an existing guide/document

Note: You need to do this only if your existing guide or document is not already using the guides_style_18f gem or if it does not have an 18f-pages branch.

Add the guides_style_18f gem to your guide's Gemfile, if it's not already present. You may also wish to copy the ./go script from the template if your document doesn't already have one.

To receive layout updates, as well as any new styles or scripts associated with them, you will need to run ./go update_theme. Or — if you aren't using a ./go script — you can run bundle update --source guides_style_18f manually.)

If your repository already has a gh-pages branch, you can create an 18f-pages branch from it by running these commands:

$ git checkout -b 18f-pages gh-pages
$ git push origin 18f-pages

Follow the instructions in Update the Config File to update your _config.yml accordingly. You may also need to consult the GitHub Setup and Post Your Guide chapters to ensure your guide is correctly published to pages.18f.gov and linked from the main 18F Guides site.