Home

Awesome

vim-instant-markdown

open collective badge

Want to instantly preview finicky markdown files, but don't want to leave your favourite editor, or have to do it in some crappy browser text area? vim-instant-markdown is your friend! When you open a markdown file in Vim, a browser window will open which shows the compiled markdown in real-time, and closes once you close the file in Vim.

As a bonus, github-flavored-markdown is supported, and styles used while previewing are the same as those GitHub uses!

Screenshot

Installation

Quick start (assuming you have all the necessary dependencies):

Detailed instructions

Arch-based distributions

Configuration

Minimal default configuration:

filetype plugin on
"Uncomment to override defaults:
"let g:instant_markdown_slow = 1
"let g:instant_markdown_autostart = 0
"let g:instant_markdown_open_to_the_world = 1
"let g:instant_markdown_allow_unsafe_content = 1
"let g:instant_markdown_allow_external_content = 0
"let g:instant_markdown_mathjax = 1
"let g:instant_markdown_mermaid = 1
"let g:instant_markdown_logfile = '/tmp/instant_markdown.log'
"let g:instant_markdown_autoscroll = 0
"let g:instant_markdown_port = 8888
"let g:instant_markdown_python = 1
"let g:instant_markdown_theme = 'dark'

After installing the plugin, execute :help vim-instant-markdown-configuration to read more about what the different configuration options imply.

Supported Platforms

OSX, Linux^, and Windows^^.

<sub>^ One annoyance in Linux is that there's no way to reliably open a browser page in the background, so you'll likely have to manually refocus your Vim session every time you open a Markdown file. If you have ideas on how to address this I'd love to know!</sub>

<sub>^^ In Windows, there's no easy way to execute commands asynchronously without popping up a cmd.exe window. Thus, if you run this plugin without g:instant_markdown_slow, you might experience performance issues.</sub>

FAQ

  1. It's not working!

    • Make sure instant-markdown-d was installed and verify using InstantMarkdownDPath.
    • Try to launch with Vim and vim-plug and this minimal.vimrc as vim -u vim -u minimal.vimrc my_markdown_file.md
    • If you're on OSX and are using zsh, try to add set shell=bash\ -i in your .vimrc to set interactive bash as the default Vim shell. (See this issue)
  2. How to start it when autostart is off?

    You can use the command :InstantMarkdownPreview to manually start the preview. <br> BTW, to disable it, use :InstantMarkdownStop.

If you're curious, the code for the mini-server component for this plugin can be found at http://github.com/instant-markdown/instant-markdown-d. A plugin can easily be written for any editor to interface with the server to get the same functionality found here.