Why this post

As I realize that I need to write a bunch of math formulas in my blog, I am searching for a way to write \(\LaTeX\) in Markdown and then render that in HTML. Mathjax jumps on my browser when I search on Google. However, when I try to integrate it with Jekyll (specifically, GitHub pages), I ran into errors after following many (top-ranked) stackoverflow / official doc instructions.

What do you need to do – Simple 4 Steps

Disclaimer:

The following guide has been proved to work on GitHub Pages using Jekyll. The theme you use should not affect anything, but I can only say for Minimal Mistakes (the theme I chose to use) everything works perfectly.

Note that It may (and will!) be different if you use other blog frameworks (e.g. Hexo) or are hosting your sites on other platforms.

1. In your _config.yml, stick with kramdown. Some instructions may tell you to go with maruku or redcarpet. Don’t. Those instructions are either outdated or do not fit GitHub Pages. Keep using kramdown by making sure there is no markdown: xxx (xxx is something other than kramdown; it is also okay if you don’t have this line as it is by default kramdown) in your _config.yml. kramdown is the only Markdown engine GitHub Pages officially supports right now.

2. This step is sort of theme dependent: If you have _include folder and there is either script.html or head.html there, you can add the following codes to one of those files. Otherwise, you may go to _layouts and add the codes to default.html. Then your post / whatever sites that need mathjax should implicitly or explicitly be using the default layout.

   {% if page.usemathjax %}
   <script type="text/javascript" async
    src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML">
     </script>
   {% end if %}
   

   Some sites may ask you to use the code from this source: http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML. This does not work for me, but is worth trying. (I think this somehow relates to AMS that is used for autoNumber but didn’t get it to work).

3. Then in the post / sites markdown file that you want to use mathjax, include the following in your YAML front matter (the table between three dash lines at the very beginning): usemathjax: true

   This will set page.usemathjax to True when Jekyll use the liquid template to generate HTML, and thus adding the script to you page.

4. To use mathjax, simply write your \(\LaTeX\) codes between a double dollar-sign. Wahoo! That’s it! You are all set!