render-markdown.nvim
Plugin to improve viewing Markdown files in Neovim
[!NOTE]
Repo has been renamed from
markdown.nvim
to make things more consistent.Github will redirect all requests so nothing should break for most users.
For
lazy.nvim
&tokyonight.nvim
users changing the plugin name will remove custom highlights until the following is merged #620.In the meantime you can fix this by adding the following to your config:
require('tokyonight').setup({ plugins = { markdown = true }, })
For
rocks.nvim
users migrate to the new LuaRock.:Rocks prune markdown.nvim :Rocks install render-markdown.nvim
Features
- Functions entirely inside of Neovim with no external windows
- Changes between
rendered
view in normal mode andraw
view in all other modes - Supports anti-conceal behavior, removing any virtual text added by this plugin on the line the cursor is on, this does have a performance penalty and can be disabled
- Changes window options between
rendered
andraw
view based on configuration- Effects
conceallevel
&concealcursor
by default
- Effects
- Supports rendering
markdown
injected into other file types - Renders the following
markdown
components:- Headings: highlight depending on level and replaces
#
with icon - Horizontal breaks: replace with full-width lines
- Code blocks: highlight to better stand out
- Inline code: highlight to better stand out
- List bullet points: replace with provided icon based on level
- Checkboxes: replace with provided icon based on whether they are checked
- Block quotes: replace leading
>
with provided icon - Tables: replace border characters, handles misaligned tables but does NOT align according to delimiter indicator
- Callouts
- Github & Obsidian out of the box, supports user defined as well
- Custom checkbox states 1, function similar to
callouts
- Adds icon before images / links 1
LaTeX
blocks: renders formulas iflatex
parser andpylatexenc
are installed
- Headings: highlight depending on level and replaces
- Disable rendering when file is larger than provided value
- Support custom handlers which are ran identically to builtin handlers
Requirements
- neovim
>= 0.9.0
(minimum)>= 0.10.0
(recommended) - treesitter parsers:
- markdown & markdown_inline:
Used to parse
markdown
files - latex (Optional):
Used to get
LaTeX
blocks frommarkdown
files
- markdown & markdown_inline:
Used to parse
- Icon provider plugin (Optional): Used for icon above code blocks
- System dependencies:
- pylatexenc (Optional):
Used to transform
LaTeX
strings to appropriate unicode usinglatex2text
- pylatexenc (Optional):
Used to transform
Install
lazy.nvim
{
'MeanderingProgrammer/render-markdown.nvim',
opts = {},
dependencies = { 'nvim-treesitter/nvim-treesitter', 'echasnovski/mini.nvim' }, -- if you use the mini.nvim suite
-- dependencies = { 'nvim-treesitter/nvim-treesitter', 'echasnovski/mini.icons' }, -- if you use standalone mini plugins
-- dependencies = { 'nvim-treesitter/nvim-treesitter', 'nvim-tree/nvim-web-devicons' }, -- if you prefer nvim-web-devicons
}
rocks.nvim
This plugin is available on LuaRocks
:Rocks install render-markdown.nvim
packer.nvim
use({
'MeanderingProgrammer/render-markdown.nvim',
after = { 'nvim-treesitter' },
requires = { 'echasnovski/mini.nvim', opt = true }, -- if you use the mini.nvim suite
-- requires = { 'echasnovski/mini.icons', opt = true }, -- if you use standalone mini plugins
-- requires = { 'nvim-tree/nvim-web-devicons', opt = true }, -- if you prefer nvim-web-devicons
config = function()
require('render-markdown').setup({})
end,
})
Commands
:RenderMarkdown
|:RenderMarkdown enable
- Enable this plugin- Can also be accessed directly through
require('render-markdown').enable()
- Can also be accessed directly through
:RenderMarkdown disable
- Disable this plugin- Can also be accessed directly through
require('render-markdown').disable()
- Can also be accessed directly through
:RenderMarkdown toggle
- Switch between enabling & disabling this plugin- Can also be accessed directly through
require('render-markdown').toggle()
- Can also be accessed directly through
:RenderMarkdown expand
- Increase anti-conceal margin above and below by 1- Can also be accessed directly through
require('render-markdown').expand()
- Can also be accessed directly through
:RenderMarkdown contract
- Decrease anti-conceal margin above and below by 1- Can also be accessed directly through
require('render-markdown').contract()
- Can also be accessed directly through
Setup
Checkout the Wiki for examples and images associated with different configuration options.
The full default configuration is provided below for reference.
Any part of it can be modified however for many fields this does not make much sense.
Some of the more useful fields are discussed further down.
Full Default Configuration
require('render-markdown').setup({
-- Whether Markdown should be rendered by default or not
enabled = true,
-- Maximum file size (in MB) that this plugin will attempt to render
-- Any file larger than this will effectively be ignored
max_file_size = 10.0,
-- Milliseconds that must pass before updating marks, updates occur
-- within the context of the visible window, not the entire buffer
debounce = 100,
-- Pre configured settings that will attempt to mimic various target
-- user experiences. Any user provided settings will take precedence.
-- obsidian: mimic Obsidian UI
-- lazy: will attempt to stay up to date with LazyVim configuration
-- none: does nothing
preset = 'none',
-- Capture groups that get pulled from markdown
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_checked) @checkbox_checked
(block_quote) @quote
(pipe_table) @table
]],
-- Capture groups that get pulled from quote nodes
markdown_quote_query = [[
[
(block_quote_marker)
(block_continuation)
] @quote_marker
]],
-- Capture groups that get pulled from inline markdown
inline_query = [[
(code_span) @code
(shortcut_link) @shortcut
[(inline_link) (full_reference_link) (image)] @link
]],
-- The level of logs to write to file: vim.fn.stdpath('state') .. '/render-markdown.log'
-- Only intended to be used for plugin development / debugging
log_level = 'error',
-- Filetypes this plugin will run on
file_types = { 'markdown' },
-- Vim modes that will show a rendered view of the markdown file
-- All other modes will be uneffected by this plugin
render_modes = { 'n', 'c' },
-- Set to avoid seeing warnings for conflicts in health check
acknowledge_conflicts = false,
anti_conceal = {
-- This enables hiding any added text on the line the cursor is on
enabled = true,
-- Number of lines above cursor to show
above = 0,
-- Number of lines below cursor to show
below = 0,
},
latex = {
-- Whether LaTeX should be rendered, mainly used for health check
enabled = true,
-- Executable used to convert latex formula to rendered unicode
converter = 'latex2text',
-- Highlight for LaTeX blocks
highlight = 'RenderMarkdownMath',
-- Amount of empty lines above LaTeX blocks
top_pad = 0,
-- Amount of empty lines below LaTeX blocks
bottom_pad = 0,
},
heading = {
-- Turn on / off heading icon & background rendering
enabled = true,
-- Turn on / off any sign column related rendering
sign = true,
-- Determines how the icon fills the available space:
-- inline: underlying '#'s are concealed resulting in a left aligned icon
-- overlay: result is left padded with spaces to hide any additional '#'
position = 'overlay',
-- Replaces '#+' of 'atx_h._marker'
-- The number of '#' in the heading determines the 'level'
-- The 'level' is used to index into the array using a cycle
icons = { ' ', ' ', ' ', ' ', ' ', ' ' },
-- Added to the sign column if enabled
-- The 'level' is used to index into the array using a cycle
signs = { ' ' },
-- Width of the heading background:
-- block: width of the heading text
-- full: full width of the window
-- Can also be an array of the above values in which case the 'level' is used
-- to index into the array using a clamp
width = 'full',
-- Amount of padding to add to the left of headings
left_pad = 0,
-- Amount of padding to add to the right of headings when width is 'block'
right_pad = 0,
-- Minimum width to use for headings when width is 'block'
min_width = 0,
-- Determins if a border is added above and below headings
border = false,
-- Highlight the start of the border using the foreground highlight
border_prefix = false,
-- Used above heading for border
above = '▄',
-- Used below heading for border
below = '▀',
-- The 'level' is used to index into the array using a clamp
-- Highlight for the heading icon and extends through the entire line
backgrounds = {
'RenderMarkdownH1Bg',
'RenderMarkdownH2Bg',
'RenderMarkdownH3Bg',
'RenderMarkdownH4Bg',
'RenderMarkdownH5Bg',
'RenderMarkdownH6Bg',
},
-- The 'level' is used to index into the array using a clamp
-- Highlight for the heading and sign icons
foregrounds = {
'RenderMarkdownH1',
'RenderMarkdownH2',
'RenderMarkdownH3',
'RenderMarkdownH4',
'RenderMarkdownH5',
'RenderMarkdownH6',
},
},
code = {
-- Turn on / off code block & inline code rendering
enabled = true,
-- Turn on / off any sign column related rendering
sign = true,
-- Determines how code blocks & inline code are rendered:
-- none: disables all rendering
-- normal: adds highlight group to code blocks & inline code, adds padding to code blocks
-- language: adds language icon to sign column if enabled and icon + name above code blocks
-- full: normal + language
style = 'full',
-- Determines where language icon is rendered:
-- right: right side of code block
-- left: left side of code block
position = 'left',
-- An array of language names for which background highlighting will be disabled
-- Likely because that language has background highlights itself
disable_background = { 'diff' },
-- Width of the code block background:
-- block: width of the code block
-- full: full width of the window
width = 'full',
-- Amount of padding to add to the left of code blocks
left_pad = 0,
-- Amount of padding to add to the right of code blocks when width is 'block'
right_pad = 0,
-- Minimum width to use for code blocks when width is 'block'
min_width = 0,
-- Determins how the top / bottom of code block are rendered:
-- thick: use the same highlight as the code body
-- thin: when lines are empty overlay the above & below icons
border = 'thin',
-- Used above code blocks for thin border
above = '▄',
-- Used below code blocks for thin border
below = '▀',
-- Highlight for code blocks
highlight = 'RenderMarkdownCode',
-- Highlight for inline code
highlight_inline = 'RenderMarkdownCodeInline',
},
dash = {
-- Turn on / off thematic break rendering
enabled = true,
-- Replaces '---'|'***'|'___'|'* * *' of 'thematic_break'
-- The icon gets repeated across the window's width
icon = '─',
-- Width of the generated line:
-- <integer>: a hard coded width value
-- full: full width of the window
width = 'full',
-- Highlight for the whole line generated from the icon
highlight = 'RenderMarkdownDash',
},
bullet = {
-- Turn on / off list bullet rendering
enabled = true,
-- Replaces '-'|'+'|'*' of 'list_item'
-- How deeply nested the list is determines the 'level'
-- The 'level' is used to index into the array using a cycle
-- If the item is a 'checkbox' a conceal is used to hide the bullet instead
icons = { '●', '○', '◆', '◇' },
-- Padding to add to the left of bullet point
left_pad = 0,
-- Padding to add to the right of bullet point
right_pad = 0,
-- Highlight for the bullet icon
highlight = 'RenderMarkdownBullet',
},
-- Checkboxes are a special instance of a 'list_item' that start with a 'shortcut_link'
-- There are two special states for unchecked & checked defined in the markdown grammar
checkbox = {
-- Turn on / off checkbox state rendering
enabled = true,
unchecked = {
-- Replaces '[ ]' of 'task_list_marker_unchecked'
icon = ' ',
-- Highlight for the unchecked icon
highlight = 'RenderMarkdownUnchecked',
},
checked = {
-- Replaces '[x]' of 'task_list_marker_checked'
icon = ' ',
-- Highligh for the checked icon
highlight = 'RenderMarkdownChecked',
},
-- Define custom checkbox states, more involved as they are not part of the markdown grammar
-- As a result this requires neovim >= 0.10.0 since it relies on 'inline' extmarks
-- Can specify as many additional states as you like following the 'todo' pattern below
-- The key in this case 'todo' is for healthcheck and to allow users to change its values
-- 'raw': Matched against the raw text of a 'shortcut_link'
-- 'rendered': Replaces the 'raw' value when rendering
-- 'highlight': Highlight for the 'rendered' icon
custom = {
todo = { raw = '[-]', rendered = ' ', highlight = 'RenderMarkdownTodo' },
},
},
quote = {
-- Turn on / off block quote & callout rendering