markdown-preview.nvim¶

In writing Markdown documentation with NvChad it is essential to know the tags of the language since the editor, being text-based, does not have a WYSIWYG mode for writing your document. This can be difficult during the first experiences with the editor and to help yourself, it can be useful to use a preview of the document you are writing. This gives you a way to check what you have written and to be able to experiment with the Markdown code while learning.

The iamcco/markdown-preview.nvim plugin allows you to have a preview of your document in a browser page that updates in real time. The preview provides an excellent representation of what we are writing, which certainly can help while learning to code but can also be useful to the more experienced.

Software Required¶

For the plugin to work properly, it needs the packages Node.js (an open source, cross-platform JavaScript runtime environment) and yarn (an open source JavaScript package manager), both of which can be installed from the official Rocky Linux repositories. The packages can be installed with the command:

dnf install nodejs yarnpkg

They will be used to install the additional JavaScript components necessary for its operation during the first installation, and for subsequent updates.

Installation¶

The installation of the plugin passes, as with all plugins, by a modification of the file custom/plugins/init.lua. The code to be inserted is as follows:

  ["iamcco/markdown-preview.nvim"] = {
    ft = { "markdown" },
    run = "cd app && yarn install",
  },

Analyzing the code we can say that the first line instructs Packer about the plugin to be installed, the second specifies the type of file that needs the plugin to be loaded, and the third executes a series of post-installation commands. In particular, the run option, in this case, executes the command as a shell command (set in the system variable $SHELL). The run command, by default, always uses the plugin folder as its source, so in this case it is located in the app folder and subsequently executes the yarn install command.

Once the changes have been made we have to close the editor and reopen it. This is to give it a chance to reload the configuration. Now you can install and configure the plugin with the :PackerSync command.

Using the Plugin¶

Preview Commands

Once installed we will have three commands for managing the preview. The commands will be active only if we have a markdown file in the buffer, and they are as follows:

:MarkdownPreview with this command the preview is started, a default browser page is opened, and a html server is started
:MarkdownPreviewStop command ends the preview and the browser page is closed
:MarkdownPreviewToggle allows you to switch the display from light to dark

The preview is also closed if you close the corresponding buffer (for example, with Space + x).

Mapping¶

The plugin can be easily integrated into NvChad with a custom mapping. To do so, we can put the following code in the custom/mapping.lua file:

M.mdpreview = {
  n = {
    ["<leader>pw"] = { "<cmd> MarkdownPreview<CR>", "Open Markdown Preview" },
    ["<leader>px"] = { "<cmd> MarkdownPreviewStop<CR>", "Close Markdown Preview" },
  },

  i = {
    ["<A-p>"] = { "<cmd> MarkdownPreview<CR>" },
    ["<A-x>"] = { "<cmd> MarkdownPreviewStop<CR>" },
  },
}

The first array sets the shortcuts for NORMAL mode ( n = { ) and allows you to select the two commands of markdown-preview.nvim by typing Space + p followed by the letter corresponding to the desired command.

Preview Mapping

The second array sets them for INSERT mode ( i = { ) allowing us to activate it while editing the document. Since in INSERT mode the Space key cannot be used for the shortcut, we moved the command to Alt. The Space key in INSERT mode is interpreted as a space to be inserted within the document and therefore cannot be used within the shortcuts.

We will then activate the preview with the combination Alt + p and close it with Alt + x.

Visualization¶

The developers of the plugin have included two themes in the css stylesheet that is used: one light and one dark. To select the desired theme there is a hidden button located at the top right of the page. Bringing the mouse to that location should cause the button to appear as shown in the screenshot below.

Preview Button

Selecting the dark theme switches the display to:

Preview Dark

There is also the option of using your own css stylesheet to have a display that is as close as possible to the document you are writing. The path to your css must be set in the mkdp_markdown_css variable, and you can also specify your own css file for highlighting code in mkdp_highlight_css. Both paths must be absolute paths (Ex. /home/user/your_css.css).

For a temporary change we can set the dark theme directly in NvChad by entering the following command in the statusline:

:let g:mkdp_theme = 'dark'

Conclusion¶

The iamcco/markdown-preview.nvim plugin provides a preview of the markdown document we are writing allowing us to check the result in real time. The commands can be easily integrated into the NvChad mapping for a faster workflow. There is also the possibility to customize the preview view using your own css stylesheet. More information can be found on the Project Page.

Side Preview

Dernière mise à jour: 27 septembre 2022

Author: Franco Colussi

Contributors: Steven Spencer