I write my Jekyll blog in Markdown with Vim. I often include LaTeX equations (via MathJax) in my posts and/or Liquid tags like {% include %}. MathJax equations and Liquid tags aren’t included in tpope/vim-markdown which meant that the LaTeX can mess with the syntax highlighting, as illustrated by the image below. I’ll describe a quick fix for this, resulting in the image on the right.

A lot is wrong in the image on the left: LaTeX commands are misinterpreted as misspelled words and entire paragraphs get incorrectly italicized.

Highlighting

To highlight the MathJax equations, I included these lines in my .vimrc. I set them up to only run when a Markdown file opens.

function! MathAndLiquid()
    "" Define certain regions
    " Block math. Look for "$$[anything]$$"
    syn region math start=/\$\$/ end=/\$\$/
    " inline math. Look for "$[not $][anything]$"
    syn match math_block '\$[^$].\{-}\$'

    " Liquid single line. Look for "{%[anything]%}"
    syn match liquid '{%.*%}'
    " Liquid multiline. Look for "{%[anything]%}[anything]{%[anything]%}"
    syn region highlight_block start='{% highlight .*%}' end='{%.*%}'
    " Fenced code blocks, used in GitHub Flavored Markdown (GFM)
    syn region highlight_block start='```' end='```'

    "" Actually highlight those regions.
    hi link math Statement
    hi link liquid Statement
    hi link highlight_block Function
    hi link math_block Function
endfunction

" Call everytime we open a Markdown file
autocmd BufRead,BufNewFile,BufEnter *.md,*.markdown call MathAndLiquid()

I put this in my .vimrc. I tried to include helpful comments, but I can summarize the steps:

  • Look for LaTeX equations, surrounded by $ or $$ pairs. For inline math with $, we use a regex that only works on a single line. For $$, we use vim’s region.
  • Look for Liquid tags, wrapped with {% and %} . This regex is easier.
  • We then highlight the regions we define as math and liquid with Function or Statement.

Code blocks

When I first wrote this post, I modified my Jekyll’s _config.yml file to include “GitHub Flavored Markdown” for my Markdown parser, kramdown. This isn’t necessary for nice highlighting but it’s still nice (mostly for fenced code blocks).

To tell kramdown to use GitHub flavored markdown, I included the following lines in my _config.yml:

markdown: kramdown

kramdown:
  input: GFM
  hard_wrap: false

If you use a 80-character line wrap like I do, hard_wrap is necessary to prevent kramdown putting <br> tags where ever it sees a line break in the file.

Alternative methods:

The method above worked for me; it provided basic functionality of what I needed. Of course, there are other methods to achieve similar functionality:

  • vim-markdown-jekyll, not an alternative but highlights YAML front matter. I also installed this plugin.
  • vim-pandoc-syntax, looks promising (pandoc documents can include Markdown, LaTeX and a bunch of other stuff) but a quick try couldn’t get it to work.
  • tpope/vim-liquid, no documentation, but as far as I can tell it only highlights .liquid files.
  • plasticboy/vim-markdown, provides markdown with LaTeX highlighting too (not just one color) but doesn’t highlight HTML.