mkdnflow.nvim: Fluent Navigation for Markdown Notebooks in Neovim

Markdown notebooks that behave like a graph, not a folder

Mkdnflow.nvim targets a specific setup: a collection of markdown files that the author already treats as a notebook, a wiki or a knowledge base, edited in Neovim. The plugin describes itself as fluent navigation and management of markdown notebooks, and the feature list spans link handling, navigation, tables, lists, to-do items, file management and folding. That scope is narrower than a note taking application and wider than a single keybinding. The project lists notetaking, personal knowledge management and static website building as intended uses, so the person who benefits most is someone already living in plain text files and wants the editor to understand the relationships between those files instead of treating every buffer as an isolated document. Mkdnflow.nvim brings no database, no proprietary note format and no sync service. Everything it does happens on files that any other tool can read.

Link following that separates text files from everything else

Link handling is where the plugin earns its name. The documented link support covers standard Markdown links, wiki links in both direct and piped form, automatic links, reference-style links, image links, citations written as @citekey or Pandoc-style [@citekey], and footnotes. Two behaviours stand out. First, following a link to a local path or another markdown file opens the text in the current window, while other file types and URLs are handed to the system default application. That split keeps you inside Neovim for notes but sends documents and web pages to a viewer you already use. Second, .bib based references are parsed far enough to open a url or doi field in the default browser and to open the document named in the file field, which is the part most plugins skip. Link creation works from a visual selection or from the text under the cursor, and links can be destroyed again.

Tables edited as pipes, grids and pasted data

Table support covers more than inserting a grid. The table feature set covers creation, extension by rows and columns, formatting, and column alignment across left, right and center. Two import paths stand out: pasting delimited data as a table, and importing a delimited file into a new table. For anyone pasting spreadsheet output into a note, that removes a manual conversion step. Pandoc grid table support is listed alongside the pipe syntax, which matters when the notebook is later processed by a Pandoc based static site build. Formatting and alignment act on the buffer text directly, so a table changes shape without leaving the file in an inconsistent state. The documentation does not explain how the plugin resolves column widths when a cell holds long content, and it says nothing about undo behaviour beyond the buffer's own. If your tables are wide, test that in a scratch file first.

To-do status that propagates across the notebook

To-do support is the most opinionated corner of the feature list. Beyond toggling an item's status, the feature list includes status propagation, sorting, and the ability to create to-do items from plain ordered or unordered list items. Propagation is the part to understand: a status change is written across related items rather than confined to the line you edited, which is useful in a notebook where the same task appears in a summary list and in a daily note, and risky in a notebook where similar text appears by coincidence. Customizable highlighting applies both to the status markers and to the content, so a finished item can be dimmed without being hidden. The trade-off is that one keystroke can modify lines outside your visible cursor position, and no preview or confirmation step for that spread is described.

Folding that counts the objects inside a closed section

Folding is where mkdnflow.nvim goes past stock Neovim behaviour in a way that shows how much it knows about markdown structure. Section folding is listed and fold toggling, plus indicators for folded contents that include the heading level, counts of Markdown objects such as tables, lists and code blocks, and line and word counts. A closed section becomes a one line summary that tells you what sits inside it before you open it. That helps in long research notes, where a heading alone rarely tells you whether the section holds a literature table or three paragraphs of prose. YAML block folding appears in the feature list as an unchecked box, so front matter still folds the way plain text does rather than as a named block. The planned table of contents window is unchecked for the same reason.

Renaming a file and the links that point at it

File management is small, but it keeps a link graph honest. Simultaneous link and file renaming is listed, and as-needed directory creation. Renaming a note from inside the buffer updates the references that pointed to it, so a notebook does not decay into a pile of broken wiki links after a reorganization. As-needed directory creation covers the case where a link target lives in a folder that does not exist yet, which is otherwise a common way link heavy notebooks break. What is not documented is what happens to a link when the target is renamed outside the plugin, for example by a shell move or by another editor. There is also no documented repository wide check for dead links, and no described escape hatch for undoing a rename that was applied to many files.

Reading the Makefile before you install anything

The project carries an Installation section for the plugin, and the repository top level contains plugin/, lua/, scripts/, tests/ and doc/ directories, which is the shape of a Neovim plugin with a documentation generator and a test suite attached. The install step itself is not spelled out in the documentation available for this review, so the safer route for a first run is to work from the repository and confirm the build and test targets work before adding the plugin to your own configuration. The Makefile is the fastest way to see what the project expects. Its help target lists the available targets, and the documentation lines read like this.

help:
	@echo "Available targets:"
	@echo "  make docs       - Regenerate README.md and doc/mkdnflow.txt"
	@echo "  make docs-verify - Verify docs are in sync with YAML sources"

Note what that output implies. The README and the vimdoc file under doc/ are generated artifacts, so editing them by hand is pointless: a docs-verify target exists precisely to check that the generated text still matches the YAML sources it came from.

Running the headless tests and regenerating the docs

The test target lists deps/mini.nvim as a prerequisite and drives MiniTest in headless Neovim using scripts/minimal_init.lua as the init file. That combination tells you the project expects a real Neovim binary on your path and a vendored test framework in the repository, so the suite runs without your own configuration interfering.

test: deps/mini.nvim
	nvim --headless --noplugin -u ./scripts/minimal_init.lua -c "lua MiniTest.run()"

The same pattern repeats for documentation generation, where a Python script rewrites both text files from the YAML sources.

docs:
	@python3 scripts/generate_docs.py

There is also a compatibility target that runs the suite across supported Neovim versions and states that it requires bob, an external tool listed in the Makefile comment. That target is the fastest way to find out whether the plugin still works on the Neovim version you actually run, since it tests more than the one binary on your machine.

Where mkdnflow.nvim still leaves work undone

Two roadmap items are unchecked in the feature list, and they are the ones a buyer notices. There is no table of contents window for a notebook, and YAML blocks are not folded as named blocks. The plugin also ships no build pipeline of its own. Pandoc grid tables and Pandoc-style citations are supported so that a Pandoc based static site build can consume the notebooks afterwards, which places the build step outside Neovim. A real alternative for editors who want no plugin at all is to keep plain markdown and maintain links by hand, trading the automatic rename and the folding counters for zero moving parts. Maintenance is steady but not fast: v2.22.1 and v2.22.2 landed on 2026-02-25 and 2026-02-27, then v2.22.3 and the last push arrived on 2026-07-03. The GPL-3.0 licence covers the plugin source, so anyone shipping it inside a larger product inherits the copyleft obligations of that licence, which is a question for your own legal review.

Editorial conclusion

Mkdnflow.nvim fits an editor-first workflow where notes live as plain markdown files and links between them are maintained by hand today. It is the wrong choice if you want a table of contents pane, YAML block folding or a bundled static site build, since none of those are shipped yet. Before adopting it, open a throwaway notebook, run the plugin's test suite through the Makefile, and confirm that to-do status propagation writes only where you expect it to.

Frequently asked questions

Official sources

1. Issues
2. jakewvincent/mkdnflow.nvim on GitHub
3. License: GPL-3.0
4. README
5. Releases