Vim Markdown Preview

• Intro
• Installation
• Usage
• Requirements
  • Mac OS X
  • Unix
• Options
  • Image rendering & save on buffer write
  • Hotkey
  • Browser
  • Temp File
  • Github Flavoured Markdown
  • Markdown.pl
  • Pandoc
  • Use xdg-open
• Behind the Scenes

Intro

This is a fork of JamshedVesuna/vim-markdown-preview, with some bug fixes, modifications and improvements for my personal use. This fork was first created on June 6, 2020.

A small Vim plugin for previewing markdown files in a browser.

The aim of this plugin is to be light weight with minimal dependencies. Thus, there is no polling engine or webserver involved.

Installation

• With Pathogen: Place vim-markdown-preview/ in .vim/bundle/.
• With Vundle:
  • Add Plugin 'JamshedVesuna/vim-markdown-preview' to your .vimrc.
  • Launch vim and run :PluginInstall

See more Options.

Usage

By default, when in a .markdown or .md file, and Ctrl-p is pressed, this plugin will either open a preview in your browser, or refresh your current preview (can be remapped, see Options).

Your cursor will remain in Vim.

Requirements

Mac OS X:

• Markdown or grip (for GitHub flavoured markdown)
  • If using Grip, put let vim_markdown_preview_github=1 in your .vimrc file
• Safari

Unix:

• Markdown or grip (for GitHub flavoured markdown)
  • If using Grip, put let vim_markdown_preview_github=1 in your .vimrc file
• xdotool
• Google Chrome or other browser

It is recommended to use grip when rendering Unicode characters.

Options

All options have default values and work out of the box. If you prefer to change these, just add the following lines to your .vimrc file. Note that after changing an option, you have to restart Vim for the change to take effect.

The vim_markdown_preview_toggle option

This option does two things (to be fixed by #17):

1. Display images in the preview
2. Generate preview on buffer write (Example: on :w)

There are a total of four values (0, 1, 2, 3) this option can take.

Default: 0, which maps Control p (not a buffer write) to generating the preview and does not display images.

Example: To display images with the hotkey mapping (defaults to Control p).

let vim_markdown_preview_toggle=1

Example: To display images automatically on buffer write.

let vim_markdown_preview_toggle=2

Example: To disregard images and still automatically preview on buffer write.

let vim_markdown_preview_toggle=3

The vim_markdown_preview_hotkey option

By default, this plugin maps <C-p> (Control p) to activate the preview. To remap Control p to a different hotkey, change the binding. Don't forget to add the single quotation marks.

Default: '<C-p>'

Example: Mapping Control M.

let vim_markdown_preview_hotkey='<C-m>'

The vim_markdown_preview_browser option

By default, if you are using Unix, Google Chrome is the default browser. If you are on Mac OS X, Safari is the default. Note that bug #16 does not allow cross operating system and browser support. See the wiki page for more help.

Default: 'Google Chrome'

Example: Using Google Chrome.

let vim_markdown_preview_browser='Google Chrome'

The vim_markdown_preview_temp_file option

By default, this plugin keeps the rendered .html file. If you would automatically like to remove the html file after opening it in a browser, set this option to 1. Note that removing the rendered html file with a slow browser may err.

Default: 0

Example: Remove the rendered preview.

let vim_markdown_preview_temp_file=1

The vim_markdown_preview_github option

If you prefer GitHub flavoured markdown you need to install Python grip. Note that this makes a request to GitHub's API (causing latencies) and may require authentication. This option also requires a network connection.

Default: 0

Example: Use GitHub flavoured markdown.

let vim_markdown_preview_github=1

The vim_markdown_preview_perl option

If you prefer to use John Gruber's Markdown.pl to render HTML, set the following flag:

Default: 0

Example: Use Markdown.pl to render HTML.

let vim_markdown_preview_perl=1

The vim_markdown_preview_pandoc option

If you prefer to use John MacFarlane's Pandoc to render HTML, set the following flag:

Default: 0

Example: Use Pandoc to render HTML.

let vim_markdown_preview_pandoc=1

The vim_markdown_preview_pandoc_math option

When using Pandoc for rendering HTML, one can use this option to choose how to render math in HTML from Pandoc's Markdown. The possible values for this option are "mathjax", "mathml", "webtex", "katex" and "gladtex", which are the same as the math rendering options of Pandoc. This option is added on 2020-07-20. It is available only in this fork.

Default: "mathjax"

Example: Use KaTeX to render math in HTML from Pandoc's Markdown.

let vim_markdown_preview_pandoc_math='katex'

The vim_markdown_preview_mathjax_conf option

When using Pandoc with MathJax to render HTML, one can use the option 'vim_markdown_preview_mathjax_conf' to specify a MathJax local configuration file (either a local file or a URL, quoted in single quotes '') to configure MathJax. This option is added on 2020-07-26. It is available only in this fork.

In effective only when: vim_markdown_preview_pandoc=1

Implies: vim_markdown_preview_pandoc_math='mathjax'

Example:

let vim_markdown_preview_mathjax_conf='/Users/foo/.mathjax/mathjax_conf.txt'

The vim_markdown_preview_use_xdg_open option

If your system does not come with see, and you would like to use xdg-open to view your rendered html in the browser, set the following flag:

Default: 0

Example: Use xdg-open.

let vim_markdown_preview_use_xdg_open=1

Behind The Scenes

1. First, this plugin renders your markdown as html and creates a temporary html file.
   • If image rendering is on, the html file will be in your working directory.
   • Otherwise, it will be in /tmp/.
2. Next, this plugin either opens the html file or refreshes the Google Chrome or Safari tab.
   • If you are using GitHub flavoured markdown, grip will make a call to the GitHub API and retrieve the html.
3. Lastly, if you choose, this plugin will remove the temporary file.