Theme API

Because we depend on Jekyll and Liquid, supporting modular theming requires some special considerations that are not always the most elegant solution. I expect the process to evolve over time so thanks for your feedback, patience, and support!
Recommended: View and study the repos for current published themes.

Theme Structure

Version 0.1.0 of the Theme API is intentionally super-simple.
Below is the structure of a theme as it exists in an "installed" state within Jekyll Bootstrap.

  • _includes
    • themes
      • THEME-NAME
        • default.html
        • post.html
        • page.html
        • settings.yml
  • assets
    • themes
      • THEME-NAME
        • css
          • style.css
        • images
          • smileyface.png

All themes are name-spaced to avoid conflicting with other theme files. As shown, a theme needs two main but separate directory components:

  1. ./_includes/themes/THEME-NAME
    Any template defined in this folder will be usable as a normal layout once you run
    $ rake theme:switch name="THEME-NAME".
  2. ./assets/themes/THEME-NAME
    Static assets for your theme should be namespaced via this folder. Your templates should use the liquid variable : ASSET_PATH to call these assets.


Themes should come with three layouts.

  • default.html
  • post.html
  • page.html

The default layout is the main template layout. The post and page define sub-layouts for their respective content types and get loaded into the default template.

YAML Front Matter and settings.yml

Layouts should not and cannot contain YAML Front Matter because they need to be loaded as include files.

To include YAML FRONT Matter, use the settings.yml file. Simply define valid YAML in the settings.yml file and it will automatically get loaded into the default.html YAML Front Matter.


All assets used in your layout files should be organized neatly into your theme's namespaced asset folder.

Make sure you load your assets using the following URL format:

<link rel="stylesheet" href="{{ ASSET_PATH }}/css/style.css" type="text/css" media="screen" charset="utf-8">

Note how ASSET_PATH is prepended to url for the asset.

Jekyll Bootstrap Helpers

Your theme should use JB helpers wherever possible.


  <div id="sidebar"> ... </div>
  <div id="main">
  {% include JB/analytics %}

JB/analytics should always be included in the default.html just before the closing body tag.


  <div id="post">
    {{ content }}
  <div class="comments">
    {% include JB/comments %}

JB/comments should always be included in the post.html file. Even if you don't support commenting, it should be up to the user to disable comments via the configuration settings.

More Helpers

Please consult Jekyll Bootstrap API Documentation for all available methods to use in your theme.

Fine Grained Customization

As stated the first public release of the theme API is intentionally super-simple.

Most designers need more control of the framework. I fully agree! Here are the things most requested.

  • Fine grained per page customization.
  • Arbitrary template/sub-template creation and nesting.
  • Customization of all HTML output by JB methods.
  • Custom syntax highlighting schemes.
  • Standardized Javascript API.
  • Proper page/post list ordering.

I expect to address every one of these issues but the initial release must be stable and easy. I am not a designer so rather than over-engineer, I leave it to the community to help me evolve the theming system.

Please email me or open a GitHub Issue with feedback!

Publishing Your Theme

Once your theme is looking good, you'll need to package it as a Theme Package. Assuming you followed all the directions and have a valid directory structure:

$ rake theme:package name="THEME-NAME"

This will create a folder at:


The contents of this folder is 1:1 file matching plus a packager.yml detailing information about the packaging method.


The manifest.yml file is required. It must contain a key-value for the name of your theme. Beyond that you can include description and authorship data.

name : "the-program"
website :  ""
description :  "A minimumlist theme for Jekyll + Jekyll-Bootstrap."
  name : "Yuya Saito"
  email : ""
  website : ""

Additionally you may include a readme file with instructions specific to your theme as well as any credits or information you want to pass along.


Well maybe in the future, but right now if you'd like to have your theme officially included in the theme explorer, please put your packaged theme on GitHub and notify me. I'll work out a better system shortly. Thanks!