markdown-popup.nvim

Show a markdown file in a floating window. q or Esc to dismiss; Enter to close the popup and open the file for editing in a split (quit it and you're back where you were).

The window is centered, sized to its content, and conceals markdown syntax so the text reads like a rendered document. Only one popup exists at a time; opening another replaces it.

Typical use: a personal cheatsheet, project notes, or a keymap reference bound to a key.

Requirements

• Neovim >= 0.10 (uses the bundled treesitter markdown parser for highlighting and concealing)
• No dependencies

Install

With the builtin plugin manager (Neovim 0.12+):

vim.pack.add({ "https://github.com/devjgm/markdown-popup.nvim" })

With lazy.nvim:

{ "devjgm/markdown-popup.nvim" }

Use

:MarkdownPopup path/to/file.md   " again (or q / Esc) to close

Or from Lua:

require("markdown-popup").open("path/to/file.md")
require("markdown-popup").toggle("path/to/file.md")
require("markdown-popup").close()

Recipe: a personal cheatsheet

Keep your own notes in a markdown file and pop them up with a key. Add this snippet to your init.lua:

vim.keymap.set("n", "<leader>?", function()
    require("markdown-popup").toggle(vim.fn.stdpath("config") .. "/cheatsheet.md")
end, { desc = "Cheatsheet" })

The popup shows whatever path you pass to toggle(). This snippet uses vim.fn.stdpath("config"), your Neovim config directory (:echo stdpath("config") to see it; typically ~/.config/nvim on macOS and Linux), so create your notes at ~/.config/nvim/cheatsheet.md and they live alongside your config, dotfiles-friendly. Any absolute path works just as well.

Configuration

Optional; these are the defaults:

require("markdown-popup").setup({
    max_width = 100,    -- cap on popup width, in columns
    max_height = 40,    -- cap on popup height, in rows
    border = "rounded", -- passed to nvim_open_win()
})

Development

Tasks live in the justfile:

just test     # run the test suite headlessly (nvim -l tests/run.lua)
just fmt      # format with StyLua
just check    # everything CI enforces: formatting and tests
just release v0.3.0   # check, push main, tag, push the tag

License

MIT