Search code examples
markdownkramdown

Workaround for kramdown couldn't parse math blocks correctly when using Jekyll


I encountered a problem with inline math rendering and demos can be found here. I originally thought Mathjax caused it, but after creating an issue here and it turns out the default markdown engine kramdown actually caused the problem.

For example, there are two inline math blocks wrapped around $ in the following markdown:

For each RoI (also for each class), PS RoI pooling is applied to obtain *normalized* offsets $ \Delta \hat{p}_{i, j} $ and then transformed to the real offsets $ \Delta p_{i, j} $

When kramdown translates it into HTML, the text between two underscores, i.e., {i, j} $, and then transformed to the real offsets $ \Delta p, was converted into italic text before the HTML can be further rendered into math equations.


Solution

  • This problem seems a bug in the default markdown engine kramdown. I've found a workaround, but it has only been tested with jekyll-theme-chirpy. I'm not sure which version of kramdown is being used, so this might not work for a future version of kramdown.

    The solution can be summarized as:

    1. block math should be added with $$ math $$ with a blank line both before and after $$.
    2. inline math (normal) should be added with $$ math $$ without any blank lines before or after $$.
    3. inline math (in lists) should be added with \$$ math $$, which escapes the first $.

    More details can be found on my GitHub page post here.