The 18F Guides Template is a Jekyll-based skeleton repository, built on CFPB/DOCter, that gives you a starting point for creating and publishing 18F-style documentation guides.
What is the 18F Guides Template?
The 18F Guides Template is a skeleton repository that provides a pre-configured Jekyll site for building documentation guides. It takes the name of your new guide as the destination folder when you clone it and produces a locally runnable static site that can be published to 18F Pages. It runs on Ruby and uses the Jekyll static site generator, and it is maintained by 18F, the digital service team of the U.S. government.
Key Features
- CFPB/DOCter foundation — Based on the CFPB/DOCter Jekyll template, so you start with a structure already used for documentation sites.
- Automated setup script — The included
./goscript checks your Ruby version, installs the Bundler gem if it is missing, and installs all gems required by the template. - Local preview server — Running
./go servelaunches a live preview at http://localhost:4000/, letting you see your guide as you edit. - Ruby version requirement — Requires Ruby version greater than 2.2.4; the README covers installing or upgrading Ruby on OS X with Homebrew.
- Version manager recommendation — The template suggests using rbenv or rvm to manage Ruby versions and avoid rebuilding gems after upgrades.
- Published hosting path — A published version of the template and its instructions is available at https://pages.18f.gov/guides-template/, and the repo is set up for publishing to 18F Pages.
- Public domain licensing — The project is released in the worldwide public domain under the CC0 1.0 Universal public domain dedication; contributions are released under CC0 as well.
Who is it for?
- Government digital teams — Start an 18F-style guide site using the same template structure as other 18F guides.
- Documentation maintainers — Publish process, policy, or onboarding guides without building a Jekyll site from scratch.
- Jekyll users — Use a ready-made skeleton with a local development server script and a GitHub Pages-friendly layout.
What can you do with the 18F Guides Template?
- Publish a new organizational guide: Clone the repo under a new name, follow the included template instructions, and publish a documentation site on 18F Pages.
- Prototype a guide locally: Run
./go serveto start a local server at localhost:4000 and iterate before publishing. - Study 18F's guide structure: Use the locally served or published template instructions as a step-by-step walkthrough for editing and publishing your own content.
How does the 18F Guides Template work?
- Clone the repository into a directory named after your guide, for example
git clone https://github.com/18F/guides-template.git MY-NEW-GUIDE. - Change into that directory and run
./go serve. - The script verifies Ruby compatibility, installs Bundler and the required gems, and launches a preview server at http://localhost:4000/.
- Follow the template instructions, either from the local preview or from the published version, to edit and publish your guide.
FAQ
What Ruby version does the 18F Guides Template require?
The template requires Ruby version greater than 2.2.4. You can check your installed version with ruby -v. If Ruby is missing or outdated, the README provides installation instructions, including a Homebrew method for OS X.
Is the 18F Guides Template free to use?
Yes. The project is in the worldwide public domain under the CC0 1.0 Universal public domain dedication. By submitting a pull request, contributors also agree to release their contributions under CC0.
How do I start a new guide with this template?
Clone the repository using your new guide's name as the destination folder, then run ./go serve. The automated script installs dependencies and starts a local preview at http://localhost:4000/, where you can access the template instructions.
Does the template support GitHub Pages publication?
The structure is designed for Jekyll-based static hosting, and 18F hosts guides on 18F Pages. The published template instructions at https://pages.18f.gov/guides-template/ show the intended output of a finished guide.
Do I need to install Bundler separately?
No. The ./go script installs the Bundler gem automatically if it is not already present, then installs all gems needed by the template, so you can get started with a single command.
