LSim

Editing and generating documentation site markdown and jekyll to the rescue

Getting the documentation repository

First checkout the documentation repository:

svn co svn://eimtserv.uoc.edu/LSim/trunk/lsim-docs

The repository has this structure:

  • assets - contains the images an other resources of the web site
  • _drafts - draft documentation files
  • files - resources like zip and other files used on documentation
  • _includes - utitlities to generate the site
  • _layouts - templates of the site
  • _plugins - utilities to genetate the site
  • _posts - contains the documentation files
  • 404.html
  • archive.html
  • atom.xml
  • categories.html
  • changelog.md
  • _config.yml - Jekyll configuration file
  • index.md - index page
  • pages.html
  • Rakefile
  • README.md
  • sitemap.txt
  • tags.html

Creating a new post

To add a new post just create a new file in _posts folder. You can use an exisiting file as a template:

  • Every file must include a header like this, you can use this as a template

    \---
layout: post
title: Editing and generating documentation site
tagline: markdown and jekyll to the rescue
category: development
tags: [documentation, development]
\---

  • The file name must follow this structe YYYY-MM-DD-descriptive-name.md. The date will be used as the publication date, and the name will be used in the permalink.

Editing the post

You can use markdown, textile or html to edit a post. Our recomendation is to use markdown so every file has the same markup.

Here is a little guide of the markdown syntax.

Publishing the site

Jekyll

Here is a guide to install jekyll.

You must install jekyll and pygments.

Previewing

Once you have installed jekyll, you can preview the site executing jekyll --server on the root folder of the documentation (where _config.yml is located).

This will open a local server on port 4000. You can go to http://localhost:4000 and preview the site. You can also edit files and see the results without closing the server.

Publishing

When you are done of editing the post, you can publish the site. Use jekyll --safe --no-auto.

This will generate the site on _site folder. Just copy all this folder to dpcs.uoc.edu projects/lsim folder and you are done!

Published

11 January 2013

Tags