Twid's vim-instant-markdown

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

• Great new look, no borders, resizes better, usable in a 50/50 split screen scenario.
• Major performance improvement, over the original version, due to a new 1 second (configurable) polling of markdown documents. No more slow mode! Plus Katex makes formula rendering fly, no more waiting on old MathJax.
• Links to other markdown files are now clickable and their destination is rendered. This happens as long as the liked files are within the folder tree of the markdown document for which InstantMarkdownPreview was started.
  • URLs contain the name of the file. To go back to seeing the file being edited in Neovim, a user must click the browser's back button to return to the landing page (root path, e.g. http://localhost:8090)
• Changing to another markdown buffer immediately displays that buffer, as long as it is within the same folder or subfolder of the first markdown document for which InstantMarkdownPreview was called.
  • As long as that buffer is in the folder or a sub-folder of the first markdown document for which InstantMardownPreview was started.
• Mermaid diagrams are now rendered.
• Running InstantMarkdownPreview now restarts the server. However, there is little need to restart the server when changing documents though, as it happens automatically.
• Task lists (GitHub-style) are now rendered.
• TOC are rendered with the [[TOC]] tag.
• Serves all content
  • within the folder tree where the initial markdown document is - e.g. display images, download pdfs, etc.
  • And (optionally) all content within a user's home folder (Linux/Mac) if a full path without space characters is specified.

Installation

You first need to have node.js with npm installed. Then:

git clone https://github.com/twidxuga/instant-markdown-d cd instant-markdown-d [sudo] npm -g install

• If you're on Linux, ensure the following packages are installed:
  • xdg-utils
  • curl
  • nodejs-legacy (for Debian-based systems)
• Copy the after/ftplugin/markdown/instant-markdown.vim file from this repo into your ~/.vim/after/ftplugin/markdown/ (creating directories as necessary), or follow your vim package manager's instructions, e.g. with vim-plug, add the following to your init.vim

Plug 'twidxuga/vim-instant-markdown'

• Ensure you have the line filetype plugin on in your init.vim
• Open a markdown file in vim and enjoy!

Configuration

g:instant_markdown_send_interval_secs (default = 1)

(Recommended) Refresh interval, set for best performance/visual result, 0 disables timers and renders on every key stroke, resulting in poorer performance for larger documents.

let g:instant_markdown_send_interval_secs = 1

g:instant_markdown_port (default = 8090)

(Optional) Set the port for instant-markdown-d to use

let g:instant_markdown_port = 8090

g:instant_markdown_autostart (default = 0)

let g:instant_markdown_autostart = 0

in your init.vim. You can then manually trigger preview via the command :InstantMarkdownPreview. This command is only available inside markdown buffers and when the autostart option is turned off.

g:instant_markdown_open_to_the_world (default = 0)

(Optional) By default, the server only listens on localhost. To make the server available to others in your network, edit your init.vim and add

let g:instant_markdown_open_to_the_world = 0

Only use this setting on trusted networks!

g:instant_markdown_allow_unsafe_content (default = 1)

(Recommended) By default, scripts are blocked. To allow scripts to run, edit your init.vim and add:

let g:instant_markdown_allow_unsafe_content = 1

g:instant_markdown_allow_external_content (default = 1)

(Recommended) By default, external resources such as images, stylesheets, frames and plugins are allowed. To block such content, edit your init.vim and add

let g:instant_markdown_allow_external_content = 1

g:instant_markdown_serve_folder_tree (default = 1)

(Highly recommended) By default, instant-makrdown-d will serve files from the folder tree starting with the current markdown files working directory. This is useful for serving files/images that may be linked to in the markdown being edited. This is now also recommended due to the new capability to follow links to other markdown files.

To prevent this set this option to 0 in your init.vim:

let g:instant_markdown_serve_folder_tree = 1

g:instant_markdown_serve_home_folder (default = 0)

(Optional) Serve all content referenced with full path in markdown links, from within a user's home folder. Currently path cannot contain spaces. Warning - it is not recommended to use this option in combination with let g:instant_markdown_open_to_the_world, especially on unsafe networks, sice it exposes ALL files in the user's home folder to the network.

let g:instant_markdown_serve_home_folder = 1

Example Markdown reference:

[Hackers Handbook](/home/user42/Books/HackersHandbook.pdf)

g:instant_markdown_slow (default = 0)

(Obsolete but available) Older versions of vim-instant-markdown would update the display in realtime. This version using a 1 second (configurable) polling logic that removed the need to use this option. In any case, if you like what it does, you can still add to your init.vim or .vimrc:

let g:instant_markdown_slow = 1

Before loading the plugin (for example place that in your ~/.config/nvim/init.vim). This will cause vim-instant-markdown to only refresh on the following events:

• No keys have been pressed for a while
• A while after you leave insert mode
• You save the file being edited

g:instant_markdown_autostart (default = 0)

(Optional) By default, vim-instant-markdown will automatically launch the preview window when you open a markdown file. If you want to manually control this behavior, you can specify

Supported Platforms

Neovim running on Unix/Linuxes*

This fork of instant markdown was NOT tested on other platforms, thought it may just work.

_{*: 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 everytime you open a Markdown file. If you have ideas on how to address this I'd love to know!}

Disclaimer

This fork of vim-instant-markdown is maintained and tested with my own needs and workflows in mind. It is not cross-platform, though I suspect it will work on Macs, and it definitely has bugs. Feel free to report issues and present pull requests, though it may take me some time to get to it.

Happy (Neo)Vimmig!

Twid