markmap: Markdown to mindmap, and what the monorepo actually gives you

The problem markmap solves: one outline, two views

Most mindmap tools make the diagram the source of truth. You drag nodes, and the file format underneath is something the tool owns. markmap inverts that. The source of truth is a Markdown document, and the mindmap is what that document looks like when rendered. The README states the intent in one line: "Visualize your Markdown as mindmaps."

That matters for a specific kind of user. If you already keep project plans, meeting notes, or documentation as Markdown in a git repository, you get a visual overview without maintaining a second file. Edit the outline, re-render, and the map follows. The audience is developers and technical writers who live in an editor and a terminal, not people looking for a general-purpose drawing canvas.

The project is a TypeScript monorepo under the MIT licence. The homepage is markmap.js.org, and the README links a REPL there for trying it without installing anything. It is explicitly inspired by dundalek's earlier markmap, which the README credits.

How the rendering pipeline is split across packages

The repository is a pnpm workspace with a packages/ directory and a lerna.json at the top level, so the published artifacts are separate packages rather than one bundle. The related-search terms people use (markmap js, Markmap npm, Markmap-view, Markmap React) map onto that split: there is a parser side that turns Markdown into a tree, a view side that draws the tree, and framework bindings on top.

The build is orchestrated from the root package.json through pnpm recursive scripts. Running the root build runs lint, clean, type generation, JavaScript build, and the test suite in sequence, and build:js is defined as pnpm -r build:js, which fans out to every workspace package. TypeScript declarations are generated separately from the JavaScript, which is why build:types exists as its own step. Documentation is generated with typedoc into an api directory.

One structural detail worth noting: the root package.json is marked private. You cannot install the repository root as a dependency. Consumers install the individual published packages, and the README directs readers to the docs site rather than listing package names inline.

Installing markmap and rendering a first map

The README does not include install commands. It points to the documentation at markmap.js.org/docs for detail, and the repository layout confirms a pnpm workspace. The commands below are the repository's own scripts, taken from package.json, not a consumer install path.

To work on the project itself, clone it and install with pnpm, then run the build script:

pnpm install
pnpm build

The build script chains lint, clean, types, JavaScript, and tests. If you only want the test suite, package.json defines it separately:

pnpm test

That runs vitest --run across the workspace, configured by vitest.workspace.ts at the root. For the fastest path to seeing a map at all, the README's own suggestion is the hosted REPL at markmap.js.org/repl, which needs no local setup. For editor use, the README lists a VS Code extension published on the Visual Studio Marketplace and Open VSX, plus coc-markmap and markmap.vim for Vim and Neovim, eaf-markmap for Emacs, and a community MCP server. Which package you install depends on that target, and the docs site is where the README sends you to find out.

Where markmap stops being the right tool

The honest limitation is the one implied by the whole design: the mindmap is a projection of a Markdown tree. If your content does not naturally form a hierarchy of headings and list items, you will spend your time fighting the format rather than thinking. Free-floating nodes, cross-links between branches, and arbitrary node positioning are not what a Markdown outline expresses.

There is also a maintenance signal worth reading carefully. The last push to the default branch was on 2026-09-12, which is recent. But the release list shows v0.18.0 on 2024-12-19, v0.17.0 on 2024-04-21, and v0.15.0 on 2023-07-16. Repository activity and tagged releases are not the same thing, and anyone pinning a version should check which of those is current for the package they use rather than assuming the branch state matches the published artifacts.

Finally, the README is thin on its own. It describes the project in a sentence, links a REPL, and defers everything else to the docs site. If you need to evaluate the library without leaving the repository, the answers are not in README.md; they are in the packages directory and the generated typedoc output.

markmap compared with Mermaid for diagramming from text

The most common comparison is markmap against Mermaid, and the difference is in the input grammar, not the output. Mermaid defines its own diagram syntax: you write a diagram description, and the renderer draws it. markmap takes ordinary Markdown, the same text you would commit to a README, and treats heading levels and list nesting as the tree structure. There is no separate diagram language to learn for markmap, and equally no way to express relationships that Markdown cannot express.

That trade-off decides the choice. If your diagram needs labelled edges, sequence semantics, or flow direction, Mermaid's grammar is the right tool and Markdown outlines are the wrong one. If your content is already an outline and you want a second view of it, markmap avoids the duplication that a hand-written diagram introduces. The related-search term "markmap vs mermaid" is the question people actually arrive with, and the answer is that they overlap only in the sense that both render diagrams from text.

Licence, upgrade cost, and what a version bump touches

markmap is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and licence text are preserved. That is a permissive arrangement with few obligations, but it is not legal advice and the LICENSE file in the repository is the authority.

The upgrade cost depends on which package you consume. Because the project is a monorepo with separate packages for parsing, viewing, and framework bindings, a major version bump in one does not automatically move the others. The release history shows gaps of eight months and longer between tagged releases, so the practical question is not how often versions ship but whether the package you depend on has moved since you pinned it. The root engines field requires Node 22 or later, which is a constraint on contributors building from source; whether it applies to consumers depends on the published package metadata, which the README does not reproduce.

Editorial conclusion

Adopt markmap if your notes are already Markdown and you want the mindmap to be a rendering of that file rather than a separate artifact you maintain. Skip it if you need a drag-and-drop canvas, collaborative editing, or export formats the docs do not mention. Before committing, check the docs site for the package that matches your target (browser, VS Code, Vim, Emacs) and confirm the Node version your toolchain runs, because the repository's package.json sets engines to node >=22. The last push was on 2026-09-12.

Frequently asked questions

Official sources

1. License: MIT
2. markmap/markmap on GitHub
3. Project website
4. README
5. Releases