Markmap HTML: turn a Markdown outline into a navigable map

Your outline already contains the structure. Rebuilding it by hand as boxes and connector lines creates a second version to maintain. Transform the Markdown with markmap-lib, then render its returned tree with markmap-view. Edit the outline when a branch changes; keep drawing coordinates out of the source notes.

Start with this deliberately small, fictional workshop plan:

Open the complete example · Download the full HTML source

# Workshop
## Prepare
- Room
- Materials
## Run
- Opening
- Exercise
## Follow up
- Notes

The indentation and headings describe the hierarchy. They do not assign owners or dates. Leave those out until the organizer supplies them, rather than letting a polished map imply a plan has been agreed.

Separate transformation from drawing

The markmap-lib guide documents a Transformer that returns the root tree and detected features. The markmap-view guide then uses that root to create the SVG view.

After loading compatible browser distributions of D3, markmap-lib, and markmap-view, the central operation is:

const transformer = new markmap.Transformer();
const { root, features } = transformer.transform(markdown);
const assets = transformer.getUsedAssets(features);

if (assets.styles) markmap.loadCSS(assets.styles);
if (assets.scripts) {
  await markmap.loadJS(assets.scripts, {
    getMarkmap: () => markmap
  });
}

const map = markmap.Markmap.create('#outline-map', undefined, root);

Create the target SVG before running this code. Give it a visible width and height; an unmeasured drawing area makes a successful transformation hard to distinguish from a missing diagram.

Know which files the map still needs

Loading a library from a CDN does not put that library inside your saved HTML. Likewise, the feature assets returned by the transformer can add dependencies beyond the basic renderer. Record the exact distributions and assets used by the finished page.

For a simple outline, avoid adding math, code-highlighting, or other formatting features unless the notes need them. If you require a single self-contained file, include the required scripts and styles in that file and test it with network access disabled. Saving a page that still requests those assets is a different delivery format.

The autoloader is another route for fixed Markdown in an HTML wrapper. Use it when you want automatic loading; use the explicit transformer and view APIs when your page needs to manage edits and rendering itself. Do not run both routes over the same SVG.

Keep a readable outline beside the map

Show the original Markdown as a reading copy beneath the graphic. This gives a reviewer a way to check the words without relying on the current zoom or which branches are open.

For the workshop example, check that Prepare contains Room and Materials, Run contains Opening and Exercise, and Follow up contains Notes. Those checks concern the source hierarchy. Changing the zoom should not move a note into a different branch.

If you build an editor, show an empty-input message instead of retaining the last successful map beside a blank source. Make the replacement drawing follow the current source, and clearly distinguish a view adjustment from an edit to the outline.

The existing mind map template covers a custom HTML map without this library pipeline. Markmap is useful here because Markdown remains the authoring format. Keep that Markdown with the review material in NOS so a request such as “move Materials under Run” points to a source edit, not a manually redrawn connector.