This is a Jekyll template I use for my GitHub projects documentations. It is heavily based on official Bootstrap documentation and is designed to be quickly deployed.


  • Responsive Bootstrap theme
  • Automatic syntax highlight
  • Multi-page
  • Automatic menu
  • Automatic heading anchors
  • Configurable additional links
  • Github counters
  • Twitter & Facebook buttons
  • Download options popup
  • Changelog page generated from GitHub releases



Install Jekyll

Follow the GitHub guide to install Jekyll on your computer. The big steps are:

$ apt-get install ruby ruby-dev
$ gem install bundler
$ git clone git://github.com/mistic100/jekyll-bootstrap-doc
$ bundle install
$ bundle exec jekyll serve


Adapt the _config.yml file to your project.

Name description
name Name of the project.
version Current version of the project
license License of the project
licenseUrl URL of the license text
favicon Extension of the favicon
download Configuration of the download button (see comment in the file)
headerLinks List of links to display on the right of the top menu. Each item must contain title and url keys
footerLinks List of links to display on the bottom of the page. Each item must contain title and url keys
header Configuration of the header, two colors gradient and boolean to activate or deactivate Trianglify generator
analytics Google analytics identifiers. Provide account and domain or leave empty to deactivate

Social buttons

Name description
githubButton Data used to generate GitHub Buttons. Provide user and repo
twitter.enabled Enable or disable Twitter "Tweet" button
twitter.via Account linked to "Tweet" button
twitter.hash Default hashtags for the "Tweet" button
twitter.account Account for Twitter "Follow" button. Leave empty to deactivate
facebook.enabled Enable or disable Facebook "Like" & "Share" buttons
facebook.profileUrl Profile for Facebook "Follow" button. Leave empty to deactivate



The main page is the index.html file. You can also add additional pages by creating .html files in the root folder or in any sub-folder. Each page file must begins with a template declaration:

layout: default
title: Home
description: Simple documentation template for Github pages

<!-- content -->

Set isHome to true on the main page file, the homepage will have a bigger header with a central download button.

isHome: true

Set hide to true to hide a page from the main menu, the page will still be accessible with direct link. Example.

hide: true


In order to get the right menu automatically generated you must respect some conventions.

<!-- wrap each main section with "bs-docs-section" class -->
<section class="bs-docs-section">
  <!-- each section must contain ONE h1 with an id and optionally a "page-header" class -->
  <h1 id="first-level" class="page-header">First level</h1>

  <!-- you can optionally declare sub-sections with h2/h3 with an id -->
  <h2 id="sub-section">Second level</h2>

  <h3 id="another-sub-section">Still second level</h3>

If you want an <h1-3> with an id but not visible in the menu, add a data-no-menu attribute to it.

<h2 id="my-id" data-no-menu>Title</h2>


A paragraph (§) link is added next to every <h1-5> with an id attribute in order to easily right-click and copy the link to a particular section. The link is visible when hovering the title.

Syntax highlight

The powerful Pygments highlighter is activated on the template, just wrap your unescaped source code with the {% highlight ... %} directive.

{% highlight html %}
<div>Some <b>HTML</b></div>
{% endhighlight %}

{% highlight javascript %}
alert('Some javascript');
{% endhighlight %}

Resources & links

If you need to create internal links between your pages, or include resources (JS & CSS), always start your URLs with {{site.github.url}}.

<script src="{{site.github.url}}/dist/my-script.js"></script>

<a href="{{site.github.url}}/about/index.html">About</a>


Bootbox is installed with a syntax sugar to easily create pop-in content. To use this sugar you must create a clickable element with a data-bootbox attribute and an hidden content holder with a corresponding id attribute.

<button class="btn btn-primary btn-xs" data-bootbox="my-content">Button title</button>

<div id="my-content" class="hidden" title="Pop-in title">
  Pop-in content


All available Jekyll plugins are installed by default, you can remove them by modifying the gems parameter in _config.yml. See the documentation on GitHub Help pages.


Feel free to use the bower.json to manage your front dependencies. Bower packages are added the dist directory and MUST be pushed to the repository. jQuery and Bootstrap are ignored by .gitignore as already loaded from a CDN.