jekyll-theme-guides-mbland: Jekyll theme gem for styling guides

Build Status

Provides consistent style elements for guides generated using Jekyll via its themes mechanism. Originally based on DOCter from CFPB.


In your Gemfile, include the following:

group :jekyll_plugins do
  gem 'jekyll-theme-guides-mbland'

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


@import "{{ site.theme }}";

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: jekyll-theme-guides-mbland

      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:

# This adds the "back to" breadcrumb link under the page title:
  url: ""
  text: Read more 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


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 Guides Template:

$ git clone [email protected]:mbland/guides-template.git
$ git clone [email protected]:mbland/jekyll-theme-guides-mbland.git

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

group :jekyll_plugins do
  gem 'jekyll-theme-guides-mbland', :path => '../jekyll-theme-guides-mbland'

You can find the different style assets and templates within the assets, _layouts, _includes, and _sass directories of this repository. Edit those, then rebuild the Jekyll site as usual to see the results.

Alternatively, you can copy files from these directories into your site and edit them to taste.

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 was adapted from my previous 18F/guides-style implementation.