Home
Plugin to improve viewing Markdown files in Neovim.
Please follow the main repo's README for the most up to date information regarding:
This plugin works with any buffer that has markdown injected anywhere. As a result
it is not filetype specific and we allow users to specify which to run on. For example
to run on both Markdown and Quarto files:
require('render-markdown').setup({
file_types = { 'markdown', 'quatro' },
})This plugin's main party trick is the ability to get out of the way of the user in 2 ways. The first is a via a mode change, depending on how the plugin is configured:
require('render-markdown').setup({
render_modes = { 'n', 'c' },
})By default this means that in normal and command modes you'll get a rendered
view, and in other modes such as insert the marks added by the plugin will disappear.
| Default Modes | All Modes |
|---|---|
render_modes = { 'n', 'c' } |
render_modes = { 'n', 'v', 'i', 'c' } |
 |
 |
The second is via anti-conceal behavior. Anti-conceal is a cursor row based behavior where any marks added by the plugin that are on the same row as your cursor (regardless of mode) will disappear. This allows for a much more fluid editing expience. If you prefer this can be disabled via:
require('render-markdown').setup({
anti_conceal = { enabled = false },
})For a more in depth look at individual components visit the associated page.
These allow you to set many different non default options with a single value. You can view the values for these here.
The default value is provided below:
require('render-markdown').setup({
preset = 'none',
})This lets you set whether the plugin should render documents from the start or not.
Useful if you want to use a command like RenderMarkdown enable to start rendering
documents rather than having it on by default. There are ways to accomplish the
same thing with the lazy.nvim cmd option, the point of this feature is to be
plugin manager agnostic.
The default value is provided below:
require('render-markdown').setup({
enabled = true,
})The maximum file size that this plugin will attemp to render in megabytes. This plugin only does rendering for what is visibile within the viewport so the size of the file does not directly impact its performance. However large files in general are laggy enough hence this feature. The size is only checked once when the file is opened and not after every update, so a file that grows larger than this in the process of editing will continue to be rendered.
The default value is provided below:
require('render-markdown').setup({
max_file_size = 10.0,
})This is meant to space out how often this plugin parses the content of the viewport
in milliseconds to avoid causing too much lag while scrolling & editing. For example
if you hold j once you've scrolled far enough down you'll notice that there is
no longer any rendering happening. Only once you've stopped scrolling for this debounce
time will the plugin parse the viewport and update the marks. If you don't mind the
lag or have a really fast system you can reduce this value to make the plugin feel
snappier.
The default value is provided below:
require('render-markdown').setup({
debounce = 100,
})Window options are used by the plugin to set different window level neovim option values when rendering and when not rendering a file. This is useful for 2 reasons:
- To allow options for rendering to be controlled by the plugin configuration so users don't need to set global or ftplugin options to make things work.
- Some option values are more useful for appearance and others are more useful while editing.
The default value is provided below:
require('render-markdown').setup({
win_options = {
conceallevel = {
default = vim.api.nvim_get_option_value('conceallevel', {}),
rendered = 3,
},
concealcursor = {
default = vim.api.nvim_get_option_value('concealcursor', {}),
rendered = '',
},
},
})This lets you set nearly all the options available at a buftype & filetype level.
Think of the top level configuration as the default where when the buftype or filetype
match these override values are used instead. filetype takes precedence over buftype.
By default we set:
require('render-markdown').setup({
overrides = {
buftype = {
nofile = {
sign = { enabled = false },
},
},
filetype = {},
},
})What this means is for the nofile buftype (the value for LSP hover docs) we disable
sign marks. This is because signs do not look good in hover docs which omit line
numbers. Similarly you can use this to set different code block rendering in hover
docs like disabling padding since that will cause line wraps:
require('render-markdown').setup({
overrides = {
buftype = {
nofile = {
code = { left_pad = 0, right_pad = 0 },
},
},
},
})This is largely useful for debugging more complicated issues and for plugin development, but not something you would want running all the time.
The default value is provided below:
require('render-markdown').setup({
log_level = 'error',
})This is only useful to clear errors in your healthcheck related to running plugins
that conflict with this one. If you see the error setting this value to true will
be suggested, otherwise it has no real functionality.
The default value is provided below:
require('render-markdown').setup({
acknowledge_conflicts = false,
})The various query options, while modifiable by the user, are best left alone.
New features often rely on updating the queries, overriding them in your config will prevent changes from "just working". Below are the default values:
require('render-markdown').setup({
markdown_query = [[
(atx_heading [
(atx_h1_marker)
(atx_h2_marker)
(atx_h3_marker)
(atx_h4_marker)
(atx_h5_marker)
(atx_h6_marker)
] @heading)
(thematic_break) @dash
(fenced_code_block) @code
[
(list_marker_plus)
(list_marker_minus)
(list_marker_star)
] @list_marker
(task_list_marker_unchecked) @checkbox_unchecked
(task_list_marker_checd) @checkbox_checked
(block_quote) @quote
(pipe_table) @table
]],
markdown_quote_query = [[
[
(block_quote_marker)
(block_continuation)
] @quote_marker
]],
inline_query = [[
(code_span) @code
(shortcut_link) @shortcut
[(inline_link) (full_reference_link) (image)] @link
]],
})