====== Blogging with Jekyll ====== From the [[http://wiki.github.com/mojombo/jekyll|Jekyll wiki]]: > Jekyll is a simple, blog aware, static site generator. 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 is installed on SDF, making it a particularly useful tool for MOTD users but also for any user wishing to host a weblog on his SDF webspace. ==== Advantages to using Jekyll ==== * **No databases required.** Jekyll converts marked up text files to HTML files. * **No dynamic pages.** With Jekyll your site will be composed solely of static HTML files. No CGI is necessary, reducing the load on SDF servers. * **Ease and simplicity of use.** Using Jekyll does not require any programming knowledge, and the learning curve is very shallow. At the same time, the user does not sacrifice any control to wizards and GUIs. ===== Getting started ===== Create a source directory with the following structure: * **"_config.yml"** This is the configuration file. Any settings put in here could also be declared as arguments after the "jekyll" command, but that would be a little messy. A complete explanation of options can be found [[http://wiki.github.com/mojombo/jekyll/configuration|here]]. * **"_layouts/"** This directory contains the layouts to be used throughout the site. The following files should be placed in this directory, and more layouts can be added later. They are not actual HTML files. * **"default.html"** This is the layout that will be used by every page on the site. It will determine the overall look and layout. * **"post.html"** This layout will be applied to the posts on the blog. * **"_posts/"** This directory is home to all posts. Posts are named "YYYY-MM-DD-title-of-post.textile", assuming Textile formatting is used. * **"index.html"** This is obviously the index file. Despite the file name extension, it requires a special layout so that it can be interpreted by the Liquid engine. Inside the "_config.yml" file, set the destination value to the directory that should contain the generated site: > " destination: /absolute/path/to/html " MOTD users may wish to put instead: > " destination: /absolute/path/to/html/motd " Replace "/absolute/path/to" with the path to your home directory. Type "echo $HOME" in the shell if you're unsure. ===== Using the Liquid templating engine ===== Liquid is a templating engine with which all files ending in ".html" will be processed. These files can have normal HTML that will be interpreted literally. Liquid only cares about text in between "{{" and " }}" and in between "{%" and "%}". The former denotes output markup, meaning that whatever is placed within the brackets can produce text. The latter denotes tag markup, which does not produce text but is used for comments, conditional statements, and loops. ==== Output markup ==== Output markup is fairly simple. The basic format is "{{ variable | filter }}". The variables are typically built into Jekyll, so one usually doesn't have to worry about declaring them. "site " is a variable that stores site-wide information in sub-variables. For example, "site.posts" is a list of all the site's posts. Each post has its own "post" variable, which includes information such as "post.title", "post.url", and "post.date" Another important variable is "content", which is used in templates to denote where the content will be inserted. A complete list of template data can be found [[http://wiki.github.com/mojombo/jekyll/template-data|here]]. Filters are used to manipulate theoutput of variables. When a filter is not specified ("{{ variable }}"), the variable is simply printed. Liquid has a bunch of built-in filters that can be found, along with a whole summary of using Liquid, [[http://wiki.github.com/tobi/liquid/liquid-for-designers|here]]. Jekyll also has some of its own filters, such as "number_of_words" and "array_to_sentence_string", which turns an array variable into a list of words seperated by commas and an "and." The complete list can be found [[http://wiki.github.com/mojombo/jekyll/liquid-extensions| here]], along with Jekyll's extra tags. ==== Tag markup ==== The most basic tag is "{% comment %}" / "{% endcomment %} ". Anything in between those tags is ignored. Conditional statements are possible with "{% if condition %}" / "{% endif %}". For loops are especially useful with Jekyll. Use them with "{% for item in array %}" / "{% endfor %}". ===== Creating templates ===== Let's actually get started with the blog. The first thing we need are the templates. ==== Default template ==== Remember that the templates are stored in the "_layouts/" folder and that the default template is named "default.html". Here we can put all of the HTML headers once and be done with them. This includes any meta information, a link to a stylesheet, a link to a feed, etc. For the title, we can use "