Jekyll Docs

Template for building a documentation site using Jekyll.

Copyright 2013 Untyped. Licensed under the Apache 2.0 license.

Building

The site is built with Grunt, Bower, Jekyll, and a host of plugins for each. It uses Bundler to install Jekyll and its dependencies.

To get started, install Bundler:

npm install -g grunt-cli
npm install -g bower
gem install bundle

Use Bundler to update the dependencies of the help site:

cs ./path-to-repo-root
npm install
bower install
bundle install

Finally, you have the following commands at your disposal:

# Build the site:
grunt build

# Watch everything and continuously rebuild the site (preview at http://localhost:4000):
grunt watch

# Reploy the site to your web server (requires you to customise Gruntfile.coffee):
grunt deploy

Directory Structure

We've moved some stuff around from a regular Jekyll deployment, largely to allow us to watch all source files without problems using Grunt:

Content:

• src/pages - Jekyll pages - this is where nost of your content goes, configurable in jekyll_config.yml;
• src/layouts - Jekyll layouts, configurable in jekyll_config.yml;
• src/includes - Jekyll includes, configurable in jekyll_config.yml;
• src/posts - Jekyll blog posts, configurable in jekyll_config.yml;
• src/css - Less CSS - main entry point is screen.less, sources/paths configurable in Gruntfile.coffee;
• src/js - Javascript - main entry point is site.js, sources/paths configurable in Gruntfile.coffee;
• src/images - Images - you can put these in src/pages or keep them separately here.

Build configuration:

• Gruntfile.coffee - Grunt configuration, main configuration for the build;
• jekyll_config.yml - Jekyll configuration including table of contents for the sidebar (see below).
• jekyll_plugins - custom Jekyll plugins.

Final distribution:

• dist - everything gets compiled to here.

Table of Contents

The table of contents, maintained in jekyll_config.yml, is a list of menu groups looking like this:

toc:
 - head: /index.html
   body: []

 - head: /section1/index.html
   body:
    - /section1/page1.html
    - /section1/page2.html

 - head: /section2/index.html
   body:
    - /section2/page1.html
    - /section2/page2.html

Each group consists of a head page and an array of body pages. The default stylesheet (toc.less) displays the heads of all sections and the body of the current section in the sidebar.

The table of contents is generated by two tag plugins:

• jekyll_plugins/nav_toc.rb - creates a {{ nav_toc }} tag that generates a table of contents;
• jekyll_plugins/nav_toc.rb - creates a {{ nav_pager }} tag that generates next and previous buttons.

Contributing

Fork and submit a pull request!