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.
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.
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
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
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
_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).
- 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
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.