Usage

The template follows a very simple convention of defining categories that correspond to sections in the navigation. Here are the default ones (they are listed in the _config.yml):

  • doc - Documentation
  • ref - Reference
  • tut - Tutorial
  • dev - Developers
  • post - Posts

Since Jekyll is more geared towards blog posts, specifiying a date and setting up the front-matter can get tedious. Supplied in the bin directory is a simple Ruby scripy for creating a new page:

ruby bin/jekyll-page title category [filename] [--edit]

where title is the title of page, category is one of the categories defined in the _config.yml. By default the filename will be derived from the title, but you can specify an explicit filename (without the date) by passing the third agument. Finally the --edit (or just -e) will launch the editor defined by the $EDITOR environment variable.

Example

./bin/jekyll-page "My New Page" ref

Will produce a file _posts/2013-06-05-my-new-page.md with the front-matter already defined:

---
layout: page
title: "My New Page"
category: ref
date: 2013-06-05 12:00:00
---

Simply add an order attribute to the front-matter of the page and the navigation links will be sorted accordingly (within it’s section).

---
layout: page
title: "My New Page"
category: ref
date: 2013-06-05 12:00:00
order: 1
---

Note: currently there is no way to arbitrarily order pages in Jekyll without the use of plugins. However, since deploying Jekyll sites to GitHub Pages is a common practice, we cannot rely on third-party plugins since they are disabled. This solution relies on JavaScript to sort the navigation after it has been rendered, so if JavaScript is disabled on the browser, the client is out of luck.

For convenience, a new directory will be created called _pages which contains symlinks to the posts without the data prefix, e.g. 2013-04-13-foo.md → foo.md. This makes it a tad easier when opening files to edit.

Disqus

You can enable disqus comments on any page. Configure your disqus shortname in the main _config.yaml, you get the shortname during the signup process at Disqus:

disqus_shortname: your_disqus

You can now enable it on a per-page basis in the YAML pre-amble of the page:

---
layout: page
title: "My New Page"
category: ref
date: 2013-06-05 12:00:00
disqus: 1
---

### Google Analytics

You can use Google Analytics to track visits to your site, once you configured your site at Google you’ll get a site ID that looks something like UA-99999999-9, to activate it on all your pages configure the _config.yaml:

google_analytics_id: 'UA-99999999-9'

If you do not wish this feature enabled you must set it to an empty string:

google_analytics_id: ''