New site generator
I finally moved my pages from a static page generation system that I cobbled together with git, makefiles, pandoc, and css, to the Jekyll based pages you are reading right now.
My old site generation setup lacked several things, including:
- mobile awareness
- blog awareness with support for comments
- support for social network sharing
- support for RSS syndication
Of these, the most problematic was the lack of mobile awareness. What my old site had, was nice support for my habit of writing posts in markdown, with LaTeX math and Bibtex references, and compatibility with Github Pages.
After a little research I ended with
- jekyll as the site generator,
- with jekyll-pandoc-multiple-formats for enabling pandoc markdown, and
- the Minimal Mistakes theme.
While the jekyll and theme combo is designed to work with Github Pages, using pandoc apparently breaks this. I decided this did not matter, as I have an alternative hosting mechanism.
Transferring the content from my old site to the new was pretty easy. However there were some minor snags that I was only able to resolve with “manual” intervention. Some highlights are
Resolving resource links. The posts end up in a particular site location without relative links being preserved. The trick was to move any resources into a
/assets/subtree, and transform[text](resource)to[text]({{site.baseurl}}/assets/resource).Fixing syntax highlighting. The pandoc syntax highlighting in combination with my chosen jekyll theme did not look good (not highlighting and double spacing). I added
--no-highlightto theflags:child in thepandoc:tree in_config.ymlfile. Now the code gets wrapped in<pre><code>tags. This allows the use of highlight.js for syntax highlighting. I selected my languages anddownloaded the zip’ed package and unpacked it in my
/assets/directory, thenadded
<link rel="stylesheet" href="/staal/assets/styles/default.css"> <script src="/staal/assets/highlight.pack.js"></script> <script>hljs.initHighlightingOnLoad();</script>to the
<head>section of the theme’s_layouts/default.htmlfile. This I downloaded from the github repo directly.
Mathjax. I like having Mathjax render math in my pages. This did not work right out of the box. I had to
add
--mathjaxto aforementionedflags:child of thepandoc:tree in_config.yml, andinsert
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"> </script>
in the theme’s
_layouts/default.htmlfile.
There might be more elegant ways of achieving the above, but it works so far.
A final thing that helped me was to download the _config.yml file from the test directory of the master branch here.