Publish Website

Publishing Web Site


Our website are static HTML pages which are generated by Jekyll from Markdown files located in the doc/ directory.

The generated files will be put in the docs/ directory (note the extra s). GitHub serves the website from this directory off the master branch.


To preview site locally

  • Run:

  • Site should be live at localhost:4000

To publish the site

  • Make sure your doc and site changes have been committed to your branch and your branch is clean.
  • Run:

  • Sanity check the diffs.

    • git diff HEAD~
  • Create a pull request for your branch and let somebody review it.

  • Merge the pull request into the master branch.


Directory Structure

We have three main directories:

  • doc/ - original content
  • docs/ - generated website actually served at
  • - all relevant files for the website e.g.
    • Jekyll configuration
    • images e.g. our logo
    • CSS
    • Navigation menu
    • boiler plate markdown files which include the actual content from the doc/ directory (example)

The boiler plate markdown files have multiple purposes:

Changing Content

To modify our website, you need to:

  • change the underlying Markdown files in the doc/ directory
  • re-generate the static pages (see above)
  • merge your changes into the master branch e.g. as pull request

Linking pages

Always use the {% link ... %} template tag to link other pages.

Note that you have to refer to the .md file of the page. Example:

[GitHub Workflow page]({% link contributing/ %})

Adding new Pages

If you want to add a new page, you must also:

When you add a new section to the menu, please create a new directory below For example, the "Contributing" section is served out of

The main file in the section should have as its boiler plate counter part. Example: doc/ is included by and therefore served as

Make sure that you use {% link ... %} to generate the URLs. See existing entries for examples.

Orphaned doc/ Markdown Files

There are several files in doc/ which are currently not visible on


This is fine and accepted. Users can still view them on

Note that these files should include images using the full path e.g. in


Otherwise GitHub cannot find and show the images.

Jekyll Install Instructions

This section describes how to install Jekyll to generate the website.

The Easy Way

  • Install Docker.
  • Run the ./ and ./ commands as shown above.

The Hard Way

  • On Ubuntu, you need a non-root Ruby install so gem packages can be installed correctly.
    • Install rbenv.
    • Close and re-open your shell to complete the installation.
    • Install ruby-build plugin for rbenv.
    • Use rbenv to build a recent version of Ruby.
    • rbenv install 2.2.3
    • You may need to install extra dependencies. The build output should tell you which packages. For example: sudo apt-get install -y libreadline-dev
    • Set the new Ruby as the system-wide default.
      • rbenv global 2.2.3
      • rbenv rehash
  • Install bundler.
    • gem install bundler
  • Install "nodejs" as JavaScript runtime.
    • sudo apt-get install nodejs
    • In Ubuntu, the binary is unfortunately renamed from "node" to "nodejs". We work-around this by creating a "node" symlink on a directory which is early in the PATH list: ln -s /usr/bin/nodejs $HOME/.rbenv/bin/node
  • Add --docker=false to the commands above.