Skip to content

Instantly share code, notes, and snippets.

@mikelove
Last active July 5, 2018 06:46
Show Gist options
  • Save mikelove/cbf6eb431406852ba725 to your computer and use it in GitHub Desktop.
Save mikelove/cbf6eb431406852ba725 to your computer and use it in GitHub Desktop.
redcarpet vs kramdown play nice with mathjax

Issues with latex math in markdown files, for display on Github Pages (using jekyll)

Our solution: use kramdown parser, with GFM option (Github flavored Markdown). In the .Rmd, use $$ for display math and $ for inline math. then have a script which turns the inline math demarkation in the .md file from $ into $$ when appropriate (avoiding data frame usage), before uploading the .md to Github. This way, RStudio preview looks the same as the Github Pages version.

redcarpet math

  • doesn't respect $ or $$ (will parse characters within these, such as _), but has workarounds:
  • has a useful option, no_intra_emphasis, so underscores between ascii characters are not converted to <em> tags, so $x_1$ is fine
  • need to escape underscores after non-ascii characters, for example $\mathbf{x}\_1$
  • need to double escape curly bracket: \\{
  • need three backslash for new line \\\
  • = cannot be on its own line

kramdown math

  • respects $$, will not interpret anything in between these. can be used for display or inline math
  • doesn't respect $ for inline math, so then you need to escape all underscores (no such option no_intra_emphasis) and curly brackets here
  • need to double escape some characters within $, e.g. \\{, which won't render in RStudio
  • you can however use $$ for inline math: $$x_1$$ and even $$\mathbf{x}_1$$ work. Unfortunately $$ will become display math in the RStudio preview (although it will be fine with Github Pages)

kramdown other

  • hard-line wrapping is not allowed. So newline character will make new lines (whereas redcarpet and RStudio will make a paragraph from contiguous lines of text). turn off option hard_wrap
  • requires leading and trailing blank lines around # headers, while redcarpet will make a header even without a trailing blank line

both

  • both can handle backtick-fenced code blocks, redcarpet by default and kramdown with GFM option (github flavored markdown)

links:

@xiaohaoliang
Copy link

good, tks ~~

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment