Mathjax javascript librry setup

Using Jekyll for Static Web Sites

Jekyll is a popular static web site generator which is the engine behind GitHub Pages. It takes a template directory (representing the raw form of a website), runs it through Textile or Markdown and Liquid converters, and spits out a complete, static website suitable for serving with Apache or your favorite web server.

Jekyll References and Resource

Jekyll Technology Summary

  • Jekyll is written in Ruby. You don’t need to know Ruby to use it, but will will need to get a little familiar with the Ruby tools for installation, managing Ruby Gems, and dependencies.
  • Liquid Templating Engine Liquid is a markup language created by the Shopify folks that makes for easy layout creation. Liquid tags are either bound by curly braces and modulos, or double curly braces. If you use a pre-built CMS like OctoPress, you won’t need to worry too much about Liquid.
  • SASS Syntactically Awesome Stylesheets are used by many systems built on top of Jekyll instead of raw CSS3.
    • SASS is an extension of CSS3 which adds nested rules, variables, mixins, selector inheritance, and more. Sass generates well formatted CSS and makes your stylesheets easier to organize and maintain. Sass compiles SASS formatted files a CSS3 stylesheets for your web site
    • Compass is an open-source CSS Authoring Framework, that makes it easier to work with Sass. It’s not strictly necessary for setting up a website using sass, it just makes it easier.
  • Markdown is the actual markup language you use to write your blog entries and website pages. There are many variants of Markdown, and several different Markdown processors that will take Markdown and generate HTML, XHTML, LatTex, and many other file formats. See my page on Markdown Overview for a complete overview.

Front Matter


Any files that contain a YAML front matter block will be processed by Jekyll. The front matter must be the first thing in the file and takes the form of:

    layout: post
    title: "Zombie Ninjas Attack: A survivor's retrospective"
    date: 2011-07-03 5:59
    comments: true
    sharing: true
    footer: true
    categories: [peopleware, practices]
    tags: [How Google Tests Software, Clean Coder, Robert Martin, Programmer Culture]
    published: true

The following tags are defined:

Key Value Notes


post, page for Octopress

This specifies the layout file to use. Additional layout files are placed in the _layouts directory.


A text title for the page Does not need to be in quotes

Don’t put an H1 heading in pages or posts. Use the title variable instead


Of the form: 2011-07-03 5:59

Is used to determine the date of the posting. If you don’t want to show a date on your page, just remove it from the yaml.


true or false (default true)

Octopress specific. If true, enable the Disqus comments on the page.


true or false (default true)

Octopress specific. If true, enables users to share the page or post via social media.


true or false (default true)

Octopress specific. Allows the footer to be turn off.


a valid external URL

If you want to publish a linklog style post (blog entries point to external urls), simply add an external-url to your post.

category: categories:

One or more categories separated by spaces. Can also be a YAML list. eg. Blogging Octopress eg. [Milk, Pumpkin Pie]

You can specify one or more categories that the post belongs to. When the site is generated the post will act as though it had been set with these categories normally. Categories (plural key) can be specified as a YAML list or a space-separated string. Categories only apply to posts, not to pages. (Darn!)


One or more tags separated by spaces. Can also be a YAML list. eg. Good, Better, Git eg. `[Good, Bill Bourne]

Is not used by Octopress, but there are plug-in available Categories onlt apply to posts, not pages. (Darn!)


true or false

Set to false if you don’t want a post or page to show up when the site is generated.


A URL for the page (generally not needed for Octopress

If you need your processed URLs to be something other than than the default /year/month/day/title.html then you can set this variable and it will be used as the final URL. See more details about Permalinks.

Custom Variables

Many of the keys listed above are actually custom variables, which Jekyll mixes into the data that is sent to the Liquid templating engine during the conversion. For instance, if you set a title, you can use that in your layout to set the page title:

     <title>{{ page.title }}</title>

But you don’t need to worry about this, unless you are creating or modifying templates.

Here are some variables generated by Jekyll for this site:

     {{ site.categories }} 

{“Blogging”=>[], “Peopleware”=>[, , , , , , , ], “Practices”=>[, , , , , , , ], “Creative Whacks”=>[, , , ], “Agile”=>[, , , , , , ]}

     {{ site.tags }} 

{“Jekyll”=>[], “Blogging”=>[], “Dave Thomas”=>[], “Programmer Culture”=>[, ], “Warfighting”=>[], “OODA Loop”=>[], “How Google Tests Software”=>[], “Clean Coder”=>[], “Robert Martin”=>[]}

     {{ page.tags }} 

JekyllOctopressJekyll YAML Front Matter

     {{ page.categories }}