Blog Setup with Jekyll

6 minute read

I thought the first project description should be my automatic jekyll page generation.

Why tho?

At least 20% of the popular internet runs on WordPress. [1] Some years ago I hosted a WordPress blog on my server. It is really comfortable and configurable, the need for PHP and a DBS is also not a problem for anyone, you can set those up in minutes or just rent an inexpensive instance.

The main opensource WordPress platform has been become quite hardened over time, but vulnerabilities in one of the over 50.000 plugins (Feb19)[2] get discovered almost monthly. The only dynamic part of a website I would be interested in, is a comment system, otherwise my site consists of static content.

Jekyll

Jekyll logo While working on a pipeline to analyse methylome data I needed to document a lot of decisions and also wanted reports on the processed datasets. At the time I had already used Markdown (Cheatsheat [3]) with Showdown and Rmarkdown to generate HTML pages and came acrosse the Jekyll Project. Jekyll is a Ruby program, which allows the creation of static blog-like-pages with the help of Markdown and Liquid. Another really nice option is to use jekyll within a Github Pages page, then they take of automatically building your page, but they limit the plugins you can use to the ones in this gem, this is the reason I use a different configuration.

Installation

The documentation is quite useful, it is also a jekyll page. To install jekyll you will need Ruby and Bundler. Bundler can be installed after Ruby using:

gem install bundler

CI friendly Setup

After looking at some themes I decided to use the MinimalMistakes Theme [4]. I have been seeing it or a fork of it on some websites of researchers and liked the minimal design, it is also very functional and well documented. To install it, make a new directory and create a file in it with the name Gemfile and the following content:

source "https://rubygems.org"
# To upgrade, run `bundle update`.
gem "jgd" # Automatic build and git deployment
gem "jekyll" # Site Generation
gem "minimal-mistakes-jekyll" # Theme
# The following plugins are automatically loaded by the theme-gem:
#   gem "jekyll-paginate"
#   gem "jekyll-sitemap"
#   gem "jekyll-gist"
#   gem "jekyll-feed"
#   gem "jemoji"
#   gem "jekyll-data"

gem "unicode"

group :jekyll_plugins do
    gem "jekyll-archives" # Tag and category pages
    gem "jekyll-scholar" # Bibliography and citations
end

You will also need the default jekyll/minimalmistakes _config.yamlfile, which you can download from the repository:

wget https://raw.githubusercontent.com/mmistakes/minimal-mistakes/master/_config.yml

In this file add:

theme: "minimal-mistakes-jekyll"
source: src
destination: _site

This means that jekyll will read the input file from the src directory and store the resulting html pages in the _site directory. To create the directory structure in the src directory:

bundle exec jekyll new --skip-bundle --blank src

Example post and page

Now you can create posts and pages.

src/index.html

---
layout: home
author_profile: true 
---
Hi!

src/_pages/about.md

---
title: About me
layout: single
permalink: about
author_profile: true 
---
## Headline
 You can create a 404 page in app/_pages/404.md

src/_posts/2019-02-017-namestartshere.md

---
title:  "This is the post title"
# The post will only be build into the page, 
# if the date of the build reached this:
date:   2019-02-17 9:00:46 +0200 
# You can also use the --future option
categories: Category
tags: [Tag 1, Tag2]
toc: true
#toc: table of contents
published: true 
# published false overwrites the date, true doesn't
---
[Link to the page](/about)

## You can write blog stuff here
Check the minimal mistakes website for more layout options.

### Links
* [Wiki](https://wikipedia.com)
* [Google](https://google.com)

Here you can read how to create a navigation bar. Now you can build your site with:

# Build the html files
bundle exec jekyll build
# Start a small webserver on localhost:4000
bundle exec jekyll serve

Example post

Travis CI Autobuild

Jekyll logoYou can host your version control on GitHub, that allows you to use Travis CI to automatically build and publish it. Thanks to the cron function of Travis CI, it is also possible to have a working planned publish system with the date: .... option. Travis CI has two websites travis-ci.com and .org, in the future, .org will be merged with .com, so use .com. [5]

If you plan to make it your personal site, don’t use your <username>.github.io repositories master branch, as you have to use this branch for the html files, but you can use a new branch.

I use the jekyll-github-deploy Ruby script, look at the project README for all the options.[6] You could replace it with a build script.

The build is defined in the .travis.yml file in the root of the repo: [7]

language: ruby
rvm:
- 2.4.1
script: bundle exec jgd -b TARGET_BRANCH -r SRC_BRANCH -u https://${GH_TOKEN}@github.com/USERNAME/REPO.git
branches:
  only:
  - SRC_BRANCH
env:
  global:
  - NOKOGIRI_USE_SYSTEM_LIBRARIES=true
  - secure: ENCRYPTEDGHTOKEN
addons:
  apt:
    packages:
    - libcurl4-openssl-dev
sudo: false
cache: bundler

The used placeholders:

Placeholder Description
USERNAME Your GitHub username
REPO Your repo, for your personal website USERNAME.github.io
SRC_BRANCH The branch which holds the Jekyll files and the .travis.yml
TARGET_BRANCH The branch which holds the HTML files, master for USERNAME.github.io
ENCRYPTEDGHTOKEN The encrypted GitHub access token with the name GH_TOKEN. See below

You can create a GitHub access token here. It only needs the public_repo permission. Github Token Creation Never publish credentials in public visible repositories, you need to encrypt those for Travis CI.

After pushing the file to the repo, you should be able to enable in TravisCI on the website and enable Github Pages on the TARGET_BRANCH. In the settings for builds it is possible to define a cron job for periodic builds: Travis CI Cron Jobs

End

In later posts I will cover citations and the archive pages (tags, categories). If something isn’t working, feel free to contact me.

Something nice for you to check out:

The AdventureZone Podcast. The McElroy family (My Brother, My Brother and Me) playing RPG tabletop games.

References

  1. [1]BuiltWith Pty Ltd, “CMS Usage Distribution in the Top 1 Million Sites.” 2019 [Online]. Available at: Link
  2. [2]Wordpress.org, “WordPress Plugins.” 2019 [Online]. Available at: Link
  3. [3]A. Pritchard, “Markdown Cheatsheet.” 2017 [Online]. Available at: Link
  4. [4]M. Rose, “Minimal Mistakes - A flexible two-column Jekyll theme. Perfect for building personal sites, blogs, and portfolios.” 2019 [Online]. Available at: Link
  5. [5]J. Kalderimis, “Announcing support for open source projects on travis-ci.com.” 2018 [Online]. Available at: Link
  6. [6]Y. Bugayenko, “jekyll-github-deploy.” 2018 [Online]. Available at: Link
  7. [7]JekyllRb, “ Jekyll - Travis CI .” 2019 [Online]. Available at: Link