The Problem

Developers who write Markdown often need a quick visual overview of hierarchy, but Markdown viewers render only linear text. Switching to a dedicated mind‑map tool forces copy‑pasting and breaks the write‑review cycle.

What This Does

markmap converts a Markdown document into an interactive SVG/HTML mind‑map. The core logic lives in the packages monorepo:

  • packages/markmap-lib – parsers, transform pipeline, and built‑in plugins (checkbox, front‑matter, syntax‑highlight, KaTeX, etc.).
  • packages/markmap-autoloader – runtime that loads assets (JS/CSS) on demand and calls transform → render.
  • packages/markmap-cli – thin wrapper exposing a cli command (packages/markmap-cli/bin/cli.js) that reads a file, runs the autoloader, and writes the HTML output.

The most‑used public symbols are in packages/markmap-lib/src/types.ts (13 other modules import it) and the transformer functions in packages/markmap-autoloader/src/index.ts (initialize, transform, render, doRender).

How It Is Wired

Execution starts at the CLI entry point packages/markmap-cli/src/cli.ts (exported as main).

  1. CLI parsing → calls createMarkmap in packages/markmap-cli/src/index.ts.
  2. createMarkmap loads the autoloader (packages/markmap-autoloader/src/index.ts) and invokes transform on the Markdown source.
  3. transform (in the autoloader) forwards the AST to packages/markmap-lib/src/transform.ts, which walks the tree, applies plugins, and returns a MarkmapData object.
  4. The resulting data is fed to render (same autoloader file). render builds the SVG/HTML by calling renderData → transition (both hit 5 call sites each) and finally writes the output via the view module (packages/markmap-view/src/view.ts).
  5. Asset handling (getAssets, fetchAssets) pulls JS/CSS for plugins; the shared loader in packages/markmap-common/src/loader.ts resolves URLs and inserts <script>/<link> tags.

Key hot‑spots:

  • packages/markmap-lib/src/types.ts – hub with 13 inbound imports; keep its API stable.
  • packages/markmap-view/src/view.ts – 699 lines, high cognitive load; changes ripple to the rendering pipeline.
  • Repeated 6‑line blocks across fetch-assets.ts, dev-server.ts, and several plugin browser entry points; they belong in a shared helper (packages/markmap-common/src/util.ts is a candidate).

No circular imports were detected, and the internal call graph shows 194 resolved edges, with the most‑used functions (transition, transform, getAssets, fit, defer, walkTree) each called from five distinct places.

How To Use It

# clone the repo
git clone https://github.com/moses-y/markmap.git
cd markmap

# install dependencies (pnpm is the workspace manager)
pnpm install

# run the CLI on a Markdown file
pnpm --filter markmap-cli exec node packages/markmap-cli/bin/cli.js path/to/file.md -o out.html

The CLI flags are defined in packages/markmap-cli/src/cli.ts; -o selects the output HTML file. If a build step is required (e.g., to bundle the autoloader for the browser), run the Vite config in each package: pnpm --filter <package> run build (scripts are defined in the respective package.json).

Real‑World Use

A documentation pipeline can invoke the CLI during CI to generate a mind‑map for each Markdown spec file and publish the resulting HTML to a static site. Example snippet in a CI job:

- run: pnpm --filter markmap-cli exec node packages/markmap-cli/bin/cli.js docs/api.md -o public/api.html

The generated api.html can be linked from the main docs site, giving readers an interactive overview without leaving the documentation repository.

Code Health & Issues

  • HIGH – GitHub Actions use tag references (@v3, @v4). Pin to commit SHA to avoid supply‑chain risk.
  • HIGH – CI workflow does not execute the test suite; add a npm test (or pnpm test) step.
  • MEDIUM – No least‑privilege permissions for GITHUB_TOKEN in .github/workflows/ci.yml. Declare contents: read.
  • MEDIUM – Dependabot / Renovate not configured; add .github/dependabot.yml.
  • MEDIUM – No dependency‑vulnerability scan in CI; integrate dependency-review-action or osv-scanner.
  • MEDIUM – README lacks usage instructions; expand with install/run example.
  • MEDIUM – Checkout step keeps credentials; set persist-credentials: false and pass token only where needed.
  • MEDIUM – Test coverage is low (2 test files for 65 source files); add tests for high‑fan‑in modules like types.ts and view.ts.
  • LOW – CI jobs have no timeout-minutes; set a reasonable bound (e.g., 15 min).

Additional observations: the repository includes a full test suite for the HTML parser but none for the core lib or view, and the CI currently runs only linting/build steps.

The Bottom Line

markmap provides a functional Markdown‑to‑mind‑map pipeline with a clear separation between parsing, transformation, and rendering. The codebase is well‑structured but suffers from a few maintainability hotspots (large view file, duplicated asset loaders) and CI hygiene gaps. It is suitable for teams that need an embeddable mind‑map generator and are comfortable addressing the medium‑severity health issues.