I’ve never planned on writing a blog post on such an issue; however making Mathjax work with kramdown and Octopress was a pain in the neck for the past couple hours, which led me to.

Warning: This blog post was written for Kramdown v0.14, which was updated to v1.0.0 on March 10, 2013.


My initial Mathjax configuration was done in the following three steps.

1. Use kramdown

  • Install kramdown with gem install kramdown 1
  • In _config.yml, change the markdown parser from rdiscount to kramdown.
  • In Gemfile, change gem 'rdiscount' to gem 'kramdown', '~> 0.13.8'.

2. Include mathjax

  • To source/_includes/custom/head.html, append the code below:
<script type="text/x-mathjax-config">
jax: ["input/TeX", "output/HTML-CSS"],
tex2jax: {
inlineMath: [ ['$', '$'], ["\(", "\)"] ],
displayMath: [ ['$$', '$$'], ["\[", "\]"] ],
processEscapes: true,
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code']
//displayAlign: "left",
//displayIndent: "2em"
<script src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML" type="text/javascript"></script>

3. Fix right-click bug

  • This bug is well-known. In sass/base/_theme.scss, apply the change below.
- > div
+ > div#main
background: $sidebar-bg
border-bottom: 1px solid $page-border-bottom
> div
background: $main-bg
border-right: 1px solid $sidebar-border


The problem was simple: Mathjax collided with kramdown.
In particular, kramdown seemed to have trouble with inline expressions, parsing LaTex expressions as below.

  • INPUT: random variables $X_1, X_2, X_3$ from
  • OUTPUT: random variables $X_1, X_2, X_3$ from
<p>random variables $X<em>1, X</em>2, X_3$ from</p>


There are two possible solutions. 2

1. Escape Markdown syntax

Octopress converts markdown to html on the server, and Mathjax renders LaTeX on the client. Then the actual solution is as simple as the problem: escape Markdown syntax in the LaTex expressions.

  • INPUT: random variables $X\_1, X\_2, X\_3$ from
  • OUTPUT: random variables $X_1, X_2, X_3$ from

2. Use double dollar sign

This is mentioned in the kramdown documentation. You can use this regardless of the mathjax configuration that assigns a single dollar sign for inline math expressions.

  • INPUT: random variables $$X_1, X_2, X_3$$ from
  • OUTPUT: random variables from
<p>random variables $X_1, X_2, X_3$ from</p>
  1. I’ve tried using maruku instead of kramdown as some blogs said, and maruku was actually good at parsing inline equations. However, I had trouble producing new lines in block equations. Nonetheless, I’d be careful to mention one is better than the other; both maruku and kramdown are in active development, and state support to LaTeX expressions out-of-the-box

  2. A SO answer mentioned wrapping Mathjax syntax with <div></div>; however this method did not seem elegant, and failed to work in some circumstances.