Jekyll

I’m moving back to jekyll (although reluctantly) from google sites. Although google sites is extremely simple and fun to use, its lack of support for latex and mathjax makes it cumbersome when it comes to technical writing.

Reminders and Cheatsheet

Everytime I come back to this website after a little while wanting to add a new post or to change a certain feature I find myself needing a quick refresher of jekyll functioning. So here are a few notes to my future self:

• Blogs are written in markdown. So you will probably need a refresher on that. I like this cheatsheet.
• Jekyll also uses the Liquid programming language to help website designers. The most important use case for me is looping over posts and projects.

Jekyll and Ruby Quickstart

bundle exec jekyll serve # test website
bundle exec jekyll build # build website

I finally understood these commands so I’ll explain them here as a reminder. Bundler is the ruby equivalent of Python’s virtualenv. So bundle exec <...> just means to run whichever command follows by using the gem versions specified in the local Gemfile. This creates a Gemfile.lock file which “locks” the current versions in, and will be read by future bundle exec calls. See Ruby 101 for more info.

When Markdown is not enough

Sometimes, markdown is too terse of a language, and a combination of html and css might be necessary. An example of this is creating an html div to have a floating image next to text. I tried and failed though to make this work on my about page…

See jekyll’s tutorial assets page to understand the /assets/css/styles.scss and _sass/main.scss files.

Minima Theme Overwriting

The default jekyll theme, which I have kept, is minima. It is possible to override some of its default settings. For example, the code in the Mathjax section below needs to be added to every page on our website. Every page on our website includes the default.html layout included in minima. In order to override it, we make a local copy of this file in the local _layouts/ folder, and add what is necessary. To keep things clean, we add the below code in _includes/mathjax.html and then include this file in default.html by adding a Liquid include snippet { % include mathjax.html %}. See Themes in jekyll’s doc pages for more info.

Mathjax

To enable mathjax and typing latex, we just need to add a script tag with a bit of code under the default.html layout file. To do this, we need to overwrite the default minima layout, by having the local file in _layouts/default.html.

  <!-- MathJax Script -->
  <script type="text/x-mathjax-config">
    MathJax.Hub.Config({
    tex2jax: {
    inlineMath: [ ['$','$'], ["\\(","\\)"] ],
    displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
    processEscapes: true
    },
    "HTML-CSS": {
    scale: 100
    }
    });
  </script>
  <script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

This actually rendered latex on localhost, but didn’t on my github pages website. Downloading this mathjax plugin for github solved the issue for me.