As I recently just migrated my blog to use jekyll + github pages, a lot of things have changed. Most notably, the markdown processor is kramdown by default. There are a few gotchas I ran into so I am writing down some notes here.

  1. Pipe symbol \(\vert\) does not work properly, as it is reserved for use in tables in the markdown syntax. Per the doc, you have to use \vert. This is a bit annoying since \(\vert\) has been used extensively in a lot of math, such as conditional probability, absolute value, and sets.
  2. For both inline and display math, kramdown uses double dollar signs. When writing math in list, if the line contains only an inline math, it will be rendered as display math. My workaround is to add some wording to make it legit inline math. To make the MathJax default \( ... \) and \[ ... \] work, you have to escape it as \\( etc when writing markdown.
  3. I’ve not yet encountered since I am still using MathJax v2, but I’ve seen quite a few places mentioned that it’s a hassle to upgrade from v2 to v3, and there are some hiccups with Kramdown. Fingers crossed it will get better soon.