I have recently decently decided to migrate the blog away from content management systems. I apologise to those of you who are looking for old pages that are now missing. Rather than do an article dump, I’ve decided to review, and re-write some of the articles instead. The site was using WordPress for a few years, before a short stint with Drupal. While they are not too difficult to setup, these systems have many moving parts that are interdependent on each other. This can make upgrades a pain point, since there can be many components to keep track of, and new releases can sometime cause incompatibilities.

As you might have noticed, the site is now statically generated by Jekyll. Rather than having a WYSIWYG editor of the fancy CMS at your disposal, this means all the content is now written in Markdown language by hand. It’s not so bad. It feels like I’m writing a wiki page, and most of it is in a human readable text file, rather than stuck in an SQL server. Backups will be a breeze from now on. Conveniently, a lot of themes like Yat also support MathJax, Google Analytics, and translation out of the box.

For those of you interested in doing something similar, here are some instructions for getting up and running quickly with Jekyll and Yat theme. You can get your site hosted with GitHub Pages for free, but I will describe how to do it with self hosting.

Installation

Jekyll

On Ubuntu/Debian based systems, open up a terminal and type

sudo apt-get install ruby-full build-essential zlib1g-dev git

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

gem install jekyll bundler

For other operating systems, see the Jekyll installation guide.

At this point, if you wanted to create your own site, you can just type

jekyll new <name>

to create a new directory <name> with a new generated website.

Yat theme

For those who want to modify the Yat theme and get going quickly,

git clone https://github.com/jeffreytse/jekyll-theme-yat.git

which will create a folder named jekyll-theme-yat. Feel free to rename this to whatever you want afterwards.

Now, we need to install the Yat dependencies by

cd jekyll-theme-yat
bundler install

You can launch a local webserver by typing (from inside the website directory)

bundler exec jekyll serve

which should allow you to preview your website with your web browser at http://127.0.0.1:4000

Configuration

Most of the basic site configurations can be set in the _config.yml. The default Yat theme configuration gives you translation into several languages, and MathJax. You can setup Google Analytics in _config.yml.

Every time you make a change to _config.yml you might have to restart bundler exec jekyll serve. In order to first exit that application in your terminal, either close the window or type Ctrl-C.

Adding content / posts

The _posts directory contains all your article posts. All you have to do is create a new file ending in .md and start writing content in Markdown language (here is a cheatsheet). Both Yat and Jekyll have example files in that folder to help you get started (including LaTeX examples).

The - in the filename, and the ‘categories’ parameter in the markdown file itself, dictates the directory structure, so 2020-10-10-test.md with categories set to ‘blog’ will show up on your site as http://your.web.site/blog/2020/10/10/test.html.

Deployment

Jekyll defaults to a ‘development’ build to start with. To properly deploy your website, run

JEKYLL_ENV=production bundle exec jekyll build

to generate (or update) a directory called _site. Copy the contents of _site to where your webserver will look for the website.

And that’s it! Now all you have to do is worry about writing content.

– Banner photo by Barth Bailey on Unsplash