Configuration

Setting optionsCopy Anchor Link

Every option is a g:mkdp_* variable. In Neovim, you can also pass them to setup() without the mkdp_ prefix:

require("markdown-preview").setup({
  theme = "dark",
  auto_close = false,
  preview_options = { sync_scroll_type = "top" },
})

With lazy.nvim, opts calls setup() for you:

{
  "sammaji/markdown-preview.nvim",
  cmd = { "MarkdownPreviewToggle", "MarkdownPreview", "MarkdownPreviewStop" },
  ft = { "markdown" },
  opts = {
    theme = "dark",
  },
}

setup():

• warns about unknown options and values of the wrong type
• accepts true/false for switches, and turns them into 1/0
• merges preview_options into the defaults, so you only give the keys you change
• can be called again later; it re-applies the options that are read once at startup (filetypes, command_for_global, auto_start, combine_preview)

In Vim, or in Neovim without setup(), set the variables before the plugin loads, e.g. in your vimrc or in lazy.nvim's init:

let g:mkdp_theme = 'dark'
let g:mkdp_auto_close = 0
let g:mkdp_preview_options = { 'sync_scroll_type': 'top' }

Keys you leave out of g:mkdp_preview_options keep their defaults.

OptionsCopy Anchor Link

The default is shown after each name.

Opening and closingCopy Anchor Link

auto_start: 0Copy Anchor Link

Open the preview when you enter a markdown buffer.

auto_close: 1Copy Anchor Link

Close the preview page when you leave its markdown buffer for another one. Turn it off to keep the page open, and with combine_preview.

combine_preview: 0Copy Anchor Link

Use one preview page for all markdown buffers. :MarkdownPreview in another buffer switches the open page to it instead of opening a new one. Set auto_close to 0 along with it.

combine_preview_auto_refresh: 1Copy Anchor Link

With combine_preview, switch the page to a markdown buffer as soon as you enter it, without running :MarkdownPreview.

filetypes: { "markdown" }Copy Anchor Link

Filetypes that get the preview commands.

command_for_global: 0Copy Anchor Link

Make the preview commands available in every buffer, whatever its filetype.

RefreshingCopy Anchor Link

refresh_slow: 0Copy Anchor Link

0 refreshes the page as you type and move the cursor. 1 refreshes it only when you save, leave insert mode or stop moving the cursor, for large files or slow machines.

BrowserCopy Anchor Link

browser: ""Copy Anchor Link

The browser to open the preview in; empty uses the system's default browser.

• A name, such as "firefox" or "Google Chrome", is opened the way the system opens applications: open -a on macOS, start on Windows, and run as a program on Linux.
• A list is run as a command with the URL appended: { "firefox", "-P", "work" }.

See Browser and sharing for new windows, WSL and other examples.

browserfunc: ""Copy Anchor Link

Name of a Vimscript function that opens the preview instead of browser. It is called with the URL.

echo_preview_url: 0Copy Anchor Link

Show the preview URL in the command line when the preview opens.

on_start: ""Copy Anchor Link

Called with the preview URL whenever a preview page is opened. A function name, a Funcref or, in Neovim, a Lua function.

on_stop: ""Copy Anchor Link

Called when :MarkdownPreviewStop (or the toggle) stops a running preview. Same types as on_start.

Server and networkCopy Anchor Link

port: ""Copy Anchor Link

Port of the preview server; empty picks a random free port. If the port is taken, for example by the preview of another editor, the next free port is used.

open_to_the_world: 0Copy Anchor Link

Listen on all network interfaces instead of only 127.0.0.1, so other devices on your network can open the preview. The preview URL then uses your machine's IP address and carries a secret token, and the server answers nothing without it. See Sharing on your network.

open_ip: ""Copy Anchor Link

Host or IP address used in the preview URL instead of localhost, for example when you edit on a remote machine and preview on your own.

PageCopy Anchor Link

theme: ""Copy Anchor Link

"dark" or "light". Empty follows the system preference. The button in the page header switches it until the page is closed.

theme_css: ""Copy Anchor Link

Absolute path of a shadcn/ui or tweakcn theme, which changes the page's colors, fonts and radius.

markdown_css: ""Copy Anchor Link

Absolute path of a stylesheet that replaces the built-in markdown styles.

highlight_css: ""Copy Anchor Link

Absolute path of a stylesheet that replaces the built-in code highlighting colors.

page_title: "「${name}」"Copy Anchor Link

Title of the browser tab. ${name} is replaced with the file name.

images_path: ""Copy Anchor Link

Directory that relative image paths are resolved against. Empty uses the directory of the markdown file.

Preview optionsCopy Anchor Link

preview_options (g:mkdp_preview_options) controls how the page renders.

preview_options = {
  mkit = vim.empty_dict(),
  katex = vim.empty_dict(),
  uml = vim.empty_dict(),
  maid = vim.empty_dict(),
  sequence_diagrams = vim.empty_dict(),
  flowchart_diagrams = vim.empty_dict(),
  toc = vim.empty_dict(),
  disable_sync_scroll = 0,
  sync_scroll_type = "middle",
  front_matter = "hide",
  hide_yaml_meta = 1,
  content_editable = false,
  disable_filename = 0,
}

mkitCopy Anchor Link

markdown-it options. The defaults turn on raw HTML, linkify and typographer. Use { html = false } to not render raw HTML from files you don't trust.

katexCopy Anchor Link

KaTeX options, e.g. { macros = { ["\\RR"] = "\\mathbb{R}" } }. Errors are shown in red instead of stopping the page.

umlCopy Anchor Link

PlantUML: server (default https://www.plantuml.com/plantuml), imageFormat (default img, or svg), and openMarker / closeMarker (default @startuml / @enduml) for bare PlantUML blocks.

maidCopy Anchor Link

Mermaid options, e.g. { layout = "elk" } for the ELK layout of dense graphs. Mermaid's theme follows the page's light or dark theme unless you set it here.

sequence_diagramsCopy Anchor Link

js-sequence-diagrams options. The default theme is "hand"; { theme = "simple" } draws straight lines.

flowchart_diagramsCopy Anchor Link

flowchart.js options.

tocCopy Anchor Link

markdown-it-toc-done-right options. The list is a ul by default.

disable_sync_scrollCopy Anchor Link

1 stops the page from scrolling along with the cursor.

sync_scroll_typeCopy Anchor Link

How the page follows the cursor:

• "middle": keep the cursor line in the middle of the page
• "top": keep the top line of the editor window at the top of the page
• "relative": keep the cursor line at the same height as in the editor

front_matterCopy Anchor Link

YAML front matter at the top of the file:

• "hide": not shown
• "panel": a collapsed panel that shows the YAML
• "raw": rendered as markdown

hide_yaml_metaCopy Anchor Link

The older form of front_matter: 0 is "raw". front_matter wins when both are set.

content_editableCopy Anchor Link

true makes the page editable, e.g. to try out wording. Edits stay in the page and are lost on the next refresh; they are not written to the buffer.

disable_filenameCopy Anchor Link

1 hides the header with the file name.

Commands and mappingsCopy Anchor Link

These are defined in buffers with a filetype from filetypes, or in every buffer with command_for_global.

nmap <C-p> <Plug>MarkdownPreviewToggle

FunctionsCopy Anchor Link

In Neovim, :checkhealth mkdp reports the same information.

Environment variablesCopy Anchor Link

Set these before starting the editor, for debugging: