Overview

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.

Features

  • Responsive Bootstrap theme
  • Automatic syntax highlight
  • Multi-page
  • Automatic menu
  • Configurable additional links
  • Github counters
  • Twitter & Facebook buttons

Examples

Installation

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

Configuration

Adapt the _config.yml file to your project.

Name description
name Name of the project.
version Current version of the project
downloadUrl URL of the download button
license License of the project
licenseUrl URL of the license text
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

Usage

Pages

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
---

Titles

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>
</section>

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

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
</div>

Plugins

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.

Bower

Fell 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.