Votre site web avec jekyll et GitYour website with Jekyll and Git

This tutorial explains the main steps to create and manage a static website with jekyll and git.

Requirements: At the begining of the installation, I had

  • a desktop computer with Kubuntu 12.04 LTS OS. A local apache server on your computer would also be helpful to test your website locally before sending it to the server;
  • a server with Ubuntu server 12.04 LTS and a git server installed.

Overview of this tutorial:

  1. Install jekyll
  2. Make your first website
  3. Use bootstrap css
  4. Deploy your website using Git

Install

Jekyll is a static web generator written in ruby. To install it, you first need to install (both on your local computer and on your server), ruby:

sudo apt-get install ruby1.9.1 ruby1.9.1-dev make

Then, using ruby repository you can install jekyll and also kramdown, a ruby library that can convert markdown (markdown is a plain and very simple text formatting syntax that can be converted into HTML).

gem install jekyll
gem install kramdown --no-rdoc --no-ri

On you local computer, create a directory that will contain your website, say myWS then make the first file you need, the configuration file

touch config.yml

An example of configuration file is provided below:

markdown: kramdown
name: "Tuxette Chix"
description: "my website"
url: "http://www.domain-name.org"

Write your first page

This part of the tutorial is partially inspired by this tutorial which helped me a lot to begin. You jekyll website is made of the following directory/files at least (all included in the previously created dirctory myWS:

  • a directory _layouts that contains the layout of every pages in your website (you can have different layouts corresponding to different types of pages in your website but at least this directory contains a default layout called, for instance, default.html
  • a file index.md that contains the content of your website’s index page. Combined with the chosen layout, it will be converted into a proper html file. Additionally any file md or html file in myWS that begins with the proper syntax (see below) will be converted into a proper html file and added to the website.

Here is a very simple example of what can be done to obtain your first website:

Layout default.html

The part with {% if page.title %} {{ page.title }} {% endif %} corresponds to liquid syntax and reads “if a title page has been provided in the processed file, then this title is displayed. Otherwise, nothing is displayed.” Similarly {{ content }} displays the content of the processed file.

File index.md

---
layout: default
title: Welcome!
---
# Welcome on my website

## About me

My name's *tuxette* and there's nothing terribly interesting that I can tell you.

## About my blog

My blog can be seen at (this link)[http://www.domain-name.org].

The file must start with its description surrounded by --- ; the layout that the file will be combined to is default.html and the page is assigned a title “Welcome !”. Then, the content of the file is provided: the syntax used is that of kramdown: # is used to indicate h1 text, ## is for h2 (and so on), *tuxette* displays the text in italic, and hyperlinks are easily included. kramdown syntax can be combined with standard HTML for more specific needs.

Generate your first website

Then, you can generate the website using the command line (inside the directory myWS)

jekyll serve

The website is created in the directory _site and if you have an apache server installed on your computer, you can see it opening the url http://localhost:4000 in your favorite browser. Jekyll server is stopped using Ctrl+C.

Use bootstrap css

Up to now, you website is probably very ugly. You should choose a css to display it nicely. As I am far from having good tastes (as this blog is the proof of), I chose security with bootstrap. There’s a very nice way to personalize bootstrap in jekyll while staying up to date with the development of the css as described at this link (that uses the css generator less) but I was not able to deploy it on my website due to version conflicts. Thus, I opted for the easy way:

  • I downloaded bootstrap and copied it in a directory assets/bootstrap in my website’s directory. It contained css files, javascript files and fonts:
  • then I updated the file layout.htmlto allow for the use of bootstrap by adding the following header:and the following lines in footer:

Your website should now display much more nicely and you can use all components provided by bootstrap.

Deploy your website with Git

More information on git and gitolite at this page and at the end of this page (sorry, in French…).

There is many ways to deploy your website on your server. The simplest is to generate it locally and then to send the directory _site on your server by FTP. However, if you are familiar with git, you may want to use it to do the job for you: when the git repository is updated, the website is automatically re-generated on your server. Deployment methods are explained on this page and I chose the post-receive approach. To do so,

  1. I first created using the git project names mywebsite using the standard config file as explained at the end of this page;
  2. then, I created a bare repository in the directory containing git repositories on my server (on Ubuntu 12.04 LTS, using gitolite, this directory is usually /var/lib/gitolite/repositories but you can locate it using locate git otherwise). This command lines are executed being root or git user:
    mkdir mywebsite.git
    cd mywebsite
    git --bare init
  3. still on the server, I created a directory that will receive the resulting website:
    mkdir ~/jekyll-website
    chown gitolite:gitolite -R ~/jekyll-website

    (the last lines give rights to gitolite on the directory)

  4. then, in /var/lib/gitolite/repositories/mywebsite.git/hooks, I created a file named post-receive that contained instructions to be run when git receives new contents:
    GIT_REPO=/var/lib/gitolite/repositories/mywebsite.git
    TMP_GIT_CLONE=/var/lib/gitolite/tmp
    PUBLIC_WWW=/home/me/jekyll-website
    
    git clone $GIT_REPO $TMP_GIT_CLONE
    jekyll build -s $TMP_GIT_CLONE -d $PUBLIC_WWW
    rm -Rf $TMP_GIT_CLONE
    chmod o+rx -R $PUBLIC_WWW
    exit
  5. finally, on my local computer, I created a git repository corresponding to the project mywebsite in the directory myWS using
    git init

    I added all files necessary to deploy the website (hence not the ones included in _site with

    git add _layouts/*.*
    git add index.md
    git add assets/bootstrap

    and pushed them on the server after I have registered the remote repository:

    git remote add public gitolite@domain-name.org:mywebsite.git
    git push public master

You’re done. I’ll explain soon how to use jekyll-scholar and BibTeX to automatically generate a publication list from a BibTeX file.