Your 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 Your website with Jekyll and Git 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

Installer les packages R pour le cours “Getting and Cleaning Data” (coursera)Install R packages for the course “Getting and Cleaning Data” (coursera)

This post explains how to install all (or at least most of) the R packages described in the MOOC “Getting and Cleaning Data” offered by Johns Hopkins University on the MOOC coursera if you’re using Ubuntu. Moreover, it gives pratical advices for staying up-to-date with your R installation on this OS.

R installation: CRAN repository and RutteR ppa

First of all, the version of R included in Ubuntu repositories may be a bit old. I advice using the official CRAN repository editing (as root) the file /etc/apt/sources.list and adding the following line at its end:

deb http://cran.univ-paris1.fr/bin/linux/ubuntu precise/

adapt the previous line with your favorite CRAN mirror and your distribution’s name) and then

gpg --keyserver keyserver.ubuntu.com --recv-key E084DAB9
gpg -a --export E084DAB9 | sudo apt-key add -
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install r-base-core r-base-dev

Packages for the CRAN repository are built on a Launchpad PPA called RutteR. It is possible to use the PPA itself, which includes a few more packages than the CRAN repository. Installing the PPA is done using:

sudo add-apt-repository ppa:marutter/rrutter
sudo apt-get update

Curl

As explained in the first week videos of the course, data avalaible through an ‘https’ connexion can be downloaded using the option method="curl" in some functions. However, on Ubuntu, you first need curl to be installed:

sudo apt-get install curl

Packages included in the repositories

Some packages are included in the repositories and can be installed directly using the command line:

sudo apt-get install r-cran-plyr r-cran-xml r-cran-reshape r-cran-reshape2 r-cran-rmysql

Packages easily installed from R

Some packages are not available in the RutteR ppa but are nevertheless easily installed in R using the CRAN repositories:

install.packages(c("jpeg","jsonlite","data.table","httr"))

or by the bioconductor project:

source("http://bioconductor.org/biocLite.R")
biocLite("rhdf5")

The hard way: package xlsx

xlsx may be a bit tricky to install because you need rJava which itself requires a proper JVM on your system. A problem has been reported trying to simply install the package r-cran-rjava:

conftest.c:1:17: fatal error: jni.h: No such file or directory
compilation terminated.
make: *** [conftest.o] Error 1
Unable to compile a JNI program

This problem is solved by:

  • first installing openjdk version 7:
    sudo apt-get install openjdk-7-*

    The installation is properly registered by your system using

    update-alternatives --config java

    and choosing openjdk-7 as the default JVM.</li>

  • rJava can now be installed. Only, java configuration for R is updated before using the ubuntu package:
    sudo R CMD javareconf
    sudo apt-get install r-cran-rjava
  • finally, in R, run:
    install.packages("xlsx")
  • </ul>

    Now, you just have to learn how to use all these 😉

    </div>


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)</li>

  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
  6. </ol>

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

    </div>