Jekyll is a simple web site generator written in Ruby that generates static HTML sites from a template directory that contains some raw text files in various formats, parses those files with the Markdown and Liquid converters, and then creates a complete, portable, and ready-to-publish static website. This static website approach is advantegeous since the resulting website is small, fast, and easy to handle for web servers like Apache2 or nginx. It basically avoids much of the bloat that comes with typical blogs using [Wordpress] or similar blog software, and it reduces the security risks due to the lack of poorly designed plugins.
Jekyll also is the engine behind GitHub Pages used by many people to host their project pages, blogs, or websites from GitHub’s servers for free. A popular way to use Jekyll is to keep your site’s files in a (local) Git repository, to edit them locally, and then to use
git push to deploy the site to your web server.
Installing required software packages
First, you need to install Ruby, Jekyll, and Git on your local machine if you haven’t done this already. Installing Jekyll is quite easy and straightforward, and it should only take a few minutes. Before you start, make sure that your system has the following requirements installed:
- Ruby (including development headers)
workstation$ sudo apt-get install ruby ruby-dev rubygems
The best way to install Jekyll is via RubyGems. At the terminal prompt, simply run the following command to install Jekyll:
workstation$ sudo gem install jekyll
This will install all of Jekyll’s gem dependencies automatically so you don’t have to worry about them at all.
Now you need Git which you can easily using your package manager:
workstation$ sudo apt-get install git
Creating a website
The Jekyll website has a nice quick-start guide to using the tool, as well as thorough documentation. Here, we will only cover the basic usage of Jekyll, but you may refer to their documentation for day-to-day usage and customization.
Create a folder on your local computer where you want to store your website files, and create a new blog using Jekyll’s
workstation$ jekyll new new_website
This will create an
new_website/ directory containing the configuration files, a posts directory, and other required bits. Now you can enter that directory and start up a server process to preview the website in your browser:
workstation$ cd new_website workstation$ jekyll serve
Jekyll will build your blog, and after a few seconds you should be able to visit
http://localhost:4000 in your browser.
Prepare the server
For the sake of concretenes, we will assume that you have already set up a server running a web server like Apache2 or nginx. We will also assume that the document root of the web server is the
First, you will need to install Jekyll and Git. For Debian and Ubuntu, you will have to install the following packages:
server$ sudo apt-get install ruby ruby-dev rubygems git-core
To have a remote server handle the deployment for you every time you push changes using Git, you can create a user account
deploy which has all the public keys that are authorized to deploy in its
server$ sudo useradd deploy
Now change into the home directory of the newly created
deploy and create a new “bare repository” to deploy to:
server$ su deploy server$ cd server$ mkdir repos server$ cd repos server$ git init --bare new_website.git
With that in place, set up the post-receive hook is done as follows:
server$ cd new_website server$ cp hooks/post-receive.sample hooks/post-receive server$ chmod +x hooks/post-receive server$ exit
Now add the following lines to
hooks/post-receive script and make sure that the web server’s document root
/var/www has write permissions for the
GIT_REPO=$HOME/repos/new_website.git TMP_GIT_CLONE=$HOME/tmp/new_website PUBLIC_WWW=/var/www git clone $GIT_REPO $TMP_GIT_CLONE jekyll build -s $TMP_GIT_CLONE -d $PUBLIC_WWW rm -Rf $TMP_GIT_CLONE exit
Local Git repository
Now it’s time to set up a local Git repository in the same directory as the Jekyll website so that any changes you make can be tracked:
workstation$ git init . workstation$ git add . workstation$ git commit -m "Initial commit"
Run the following command on any users that need to be able to deploy using this hook:
workstation$ git remote add deploy firstname.lastname@example.org:~/repos/new_website.git
Finally, deploying is now as easy as running the following Git
workstation$ git push deploy master