Plugin to improve viewing Markdown files in Neovim
rendered
view in normal mode and raw
view in all other modesconceallevel
between rendered
and raw
view based on configurationmarkdown
injected into other file types#
>
with provided characterLaTeX
if pylatexenc
is installed on systemmarkdown
filesLaTeX
strings
to appropriate unicode using latex2text
, not a mandatory dependency{
'MeanderingProgrammer/markdown.nvim',
name = 'render-markdown', -- Only needed if you have another plugin named markdown.nvim
dependencies = { 'nvim-treesitter/nvim-treesitter' },
config = function()
require('render-markdown').setup({})
end,
}
use({
'MeanderingProgrammer/markdown.nvim',
as = 'render-markdown', -- Only needed if you have another plugin named markdown.nvim
after = { 'nvim-treesitter' },
config = function()
require('render-markdown').setup({})
end,
})
Below is the configuration that gets used by default, any part of it can be modified by the user.
require('render-markdown').setup({
-- Configure whether Markdown should be rendered by default or not
start_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 = 1.5,
-- 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 (block_quote_marker) @quote_marker)
(block_quote (paragraph (inline (block_continuation) @quote_marker)))
(pipe_table) @table
(pipe_table_header) @table_head
(pipe_table_delimiter_row) @table_delim
(pipe_table_row) @table_row
]],
-- Capture groups that get pulled from inline markdown
inline_query = [[
(code_span) @code
]],
-- 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' },
-- Characters that will replace the # at the start of headings
headings = { ' ', ' ', ' ', ' ', ' ', ' ' },
-- Character to use for the horizontal break
dash = '—',
-- Character to use for the bullet points in lists
bullets = { '●', '○', '◆', '◇' },
checkbox = {
-- Character that will replace the [ ] in unchecked checkboxes
unchecked = ' ',
-- Character that will replace the [x] in checked checkboxes
checked = ' ',
},
-- Character that will replace the > at the start of block quotes
quote = '┃',
-- See :h 'conceallevel' for more information about meaning of values
conceal = {
-- conceallevel used for buffer when not being rendered, get user setting
default = vim.opt.conceallevel:get(),
-- conceallevel used for buffer when being rendered
rendered = 3,
},
-- Add a line above and below tables to complete look, ends up like a window
fat_tables = true,
-- Define the highlight groups to use when rendering various components
highlights = {
heading = {
-- Background of heading line
backgrounds = { 'DiffAdd', 'DiffChange', 'DiffDelete' },
-- Foreground of heading character only
foregrounds = {
'markdownH1',
'markdownH2',
'markdownH3',
'markdownH4',
'markdownH5',
'markdownH6',
},
},
-- Horizontal break
dash = 'LineNr',
-- Code blocks
code = 'ColorColumn',
-- Bullet points in list
bullet = 'Normal',
checkbox = {
-- Unchecked checkboxes
unchecked = '@markup.list.unchecked',
-- Checked checkboxes
checked = '@markup.heading',
},
table = {
-- Header of a markdown table
head = '@markup.heading',
-- Non header rows in a markdown table
row = 'Normal',
},
-- LaTeX blocks
latex = '@markup.math',
-- Quote character in a block quote
quote = '@markup.quote',
},
})
:RenderMarkdownToggle
- Switch between enabling & disabling this plugin
require('render-markdown').toggle()
There are many existing markdown rendering plugins in the Neovim ecosystem. However, most of these rely on syncing a separate browser window with the buffer. This is the correct way to do things to get full feature support, however I wanted something that worked completely inside of Neovim and made things look slightly "nicer".
The closest one I found to this was headlines.nvim, which is an awesome plugin that I took several ideas from. However it just didn't have quite what I was looking for. In particular I wanted something that would disappear completely when editing a file and quickly render some style when viewing the file. Hence this plugin.
There are many markdown
plugins that specialize in different aspects of interacting
with markdown
files. This plugin specializes in rendering the buffer inside of
Neovim, for instance. As a result some plugins will clash with this one, whereas
other plugins handle orthogonal concerns and can be used in addition to this one.
Below is a categorized (incomplete) list of available plugins.
Using any of these plugins with this one will likely lead to undesired behavior as different functionality will clash.
These can be used as a second pass to get a real preview of the markdown
file.
Since they do not interact with the buffer directly there should be no issues.
These plugins handle functions completely separate from rendering and should also have no issues running alongside this plugin.
markdown
specific keybindings for interacting with markdown
files