Table of Contents
1. Install Ruby and Jekyll
To be able to write blogs with complicated mathematics, you need some way for compatibility of blogs with MathJax or LaTeX. LaTeX is often preferred among math writers because of the whole diversity of mathematical writing features available as well as it is the de-facto standard for writing research papers, articles, journals, theses, and books.
So then why Jekyll? …..
Jekyll is a static site generator with lots of cool features needed for publishing blogs and websites. Compared to more common website publishing tools, Jekyll gives you more fine-grained control over the content albeit without any steep learning curve. Jekyll is fast and offers easy integration with github for version management (making changes and keeping track) and also with publishing tools like Netlify. Icing on the cake is Jekyll offers gazillions of cool themes and designs to choose from catering to multiple needs and formats. Jekyll themes are so popular because it is not necessary to deal with all the complicated HTML stuff as you can write directly in Markdown (as simple as writing in Microsoft Word). If you want to, you can still embed HTML in between, so nothing is lost.
The most important feature of all is that many Jekyll themes allow MathJax/LaTeX integration, which along with the other features, makes it the go-to for writing math blogs!
Installation steps
Follow the steps for Jekyll installation on macOS, Windows, Ubuntu and Other Linux distros.
To get an idea of some installation issues please check Issue 1 and Issue 2.
To check successful installation try the following steps:
A new folder my-website (this is a placeholder, feel free to change to whatever name catches your fancy, for example, the name of your cat…) would have been created with all necessary jekyll and bundle packages (I am not getting into the details here as they would be taken care of by the steps a few lines back). Next try:
> cd my-website
> bundle exec jekyll serve
The bundle exec jekyll serve command above compiles the most minimalist jekyll webpage and enables it for viewing. This command is very useful as it allows on-the-fly editing and viewing your website changes locally before publishing. If everything works well, then you will be able to view your FIRST jekyll website by going to localhost:4000 in your browser. TADA!!!
2. Creating your blogging site with Jekyll and LaTeX
Well, to write a blog, the first thing to do is choose a Jekyll theme that caters to your style and of course, the tastes of your audience. For mathematical blogs, often, minimalist designs are preferred. Hence, I tried out only two out of many: Minima and Contrast. I found Contrast to be very interesting as it is MathJax-ready and also allows very nice integration with different kinds of media content. Moreover, Contrast is based on Minima and offers much more!
Working with Contrast theme
Within folder my-website (root directory of your blog) clone contrast theme codebase (which is going to be your default site codebase where you will be making changes):
> git clone https://github.com/niklasbuschmann/contrast
> cd contrast
> bundle add webrick
> bundle update
> pwd
.../my-website/contrast
To ensure LaTeX compatibility add the following line to the end of your _layouts/default.html file. The Contrast theme comes with KaTeX and MathJax compatibility by default, however, adding this will enable recognition of many TexLive features (including amsmath etc.):
<script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
Start writing….
Done with all blog configuration stuff… Now we can start writing!
To add new posts, simply add a file in the _posts directory that follows the convention YYYY-MM-DD-name-of-post.md with the necessary preamble (check this source for an example). To write in Markdown, for excellent tips and tricks refer to this article or this example to get started quickly. For more advanced stuff, please refer to the examples in the Contrast demo site (Link1 and Link 2).
Adding LaTeX stuff
This is super easy as we can just simply add $$ delimiter in the beginning and end of our LaTeX snippet (instead of the usual $ as the dollar is so common in the normal text domain). A simple example is as follows:
$$\nabla_\theta \mathbb{E}_{\tau \sim \pi_\theta}[R(\tau)] = \mathbb{E}_{\tau \sim \pi_\theta} \left[R(\tau) \cdot \nabla_\theta \left(\sum_{t=0}^{T-1}\log \pi_\theta(a_t|s_t)\right)\right]$$
will render this equation: \(\nabla_\theta \mathbb{E}_{\tau \sim \pi_\theta}[R(\tau)] = \mathbb{E}_{\tau \sim \pi_\theta} \left[R(\tau) \cdot \nabla_\theta \left(\sum_{t=0}^{T-1}\log \pi_\theta(a_t|s_t)\right)\right]\)
Also, do not forget to set mathjax: true in your blog markdown preamble. However, Jekyll and MathJax do not offer all of the functionality of LaTeX—there is no support for the LaTeX usepackage command, so only the core LaTeX functionality that has been ported to MathJax is available [Source].
Testing your blog locally
Once your file is created with the preamble and some content in Markdown/LaTeX is added (a lot of content is not needed for testing your site.. just the preamble and some basic content.. as basic as a few words…), try the following bundle exec jekyll serve command as seen before to compile your changes and test locally by entering localhost:4000 your browser.
> pwd
.../my-website/contrast
> bundle exec jekyll serve
The best part is you can keep this command running and parallelly make your changes… just refreshing your browser will show your latest changes.. this on-the-fly editing and viewing feature makes this so BEAUTIFUL!
Once this is done, all the publishable content gets populated in the _site directory. To add content like images, etc., create a directory like img under assets, so that you can add /assets/img/file.png as your image location in your blog markdown file.
We are now ready to push everything to GitHub….