Guides Template

This is a skeleton repo containing a template for "Guides" documents. It uses Jekyll as the rendering system, and the jekyll-theme-guides-mbland Ruby gem for the theme.

After setting up your environment and cloning and serving the site locally, visit http://localhost:4000/ to read the Guides Template in your browser. It will walk you through the rest of the steps to edit and publish your guide.

Getting started

If you don't have Ruby and Node.js installed, skip to the Installing Ruby and Installing Node.js sections below before proceeeding.

To create a new guide and serve it locally, where MY-NEW-GUIDE is the name of your new repository:

$ git clone https://github.com/mbland/guides-template.git MY-NEW-GUIDE
$ cd MY-NEW-GUIDE
$ ./go serve

The ./go script will check that your Ruby and Node version is supported, install the Bundler gem if it is not yet installed, install all the gems needed by the template, and launch a running instance at http://localhost:4000/.

Installing Ruby

You will need Ruby version 2.3.3 or greater. To check whether it's already installed on a UNIX-like system, open up a terminal window (e.g. Terminal on OS X) and type ruby -v at the command prompt. For example, you should see something similar to the following:

$ ruby -v
ruby 2.3.3p222 (2016-11-21 revision 56859) [universal.x86_64-darwin17]

If the version number is less than 2.3.3, or instead you see something like:

$ ruby -v
-bash: ruby: command not found

Then Ruby is not installed, and you should choose one of the installation methods below. The "Installing Ruby" page of the official Ruby language web site explains how to do this in a number of ways across many different systems.

• On macOS, consider using Homebrew:

  $ brew update
  $ brew install ruby

• You may consider using a version manager such as rbenv instead.

Installing Node.js

You will need Node.js version v4.0.0 or greater. Node.js is used by the jekyll_pages_api_search gem, integrated into the jekyll-theme-guides-mbland gem, to build the Lunr.js index.

As with Ruby above, check which version you have via:

$ node -v
v8.7.0

If you don't have version v4.0.0 or greater, or Node.js isn't installed, visit the Node.js site and download a suitable version for your system.

• On macOS, consider using Homebrew:

  $ brew update
  $ brew install node

• You may consider using a version manager such as nvm instead.

Feedback and contributions

Feel free to comment on or file a new GitHub issue or otherwise ping @mbland with any questions or comments you may have, especially if the current documentation hasn't addressed your needs.

If you'd care to contribute to this project, be it code fixes, documentation updates, or new features, please read the CONTRIBUTING file.

Open Source License

This software is made available as Open Source software under the ISC License. For the text of the license, see the LICENSE file.

Prior work

This repository was originally forked from 18F/guides-template, the content of which was derived from CFPB/DOCter.