md2hd README

The project's README from github.com/evan-steinhilb/md2hd. As one markdown file: README.md.

md2hd

Markdown, mapped. Point it at a file or a folder of notes and it opens a map in your browser — frontmatter becomes nodes, wikilinks become edges, and the topology you have been holding in your head becomes something you can look at.

npm node license

npx md2hd notes/     # a folder of markdown
npx md2hd map.md     # or a single file

Or install it for keeps: npm i -g md2hd.

An organisation map drawn from a folder of markdown — typed nodes, labelled links, a minimap, and the type strip along the foot

Why

You already have the material — organisations, people, threads, intent, all of it written down. The thing you are missing is a picture of how it fits together. md2hd draws that picture from the files you already keep, and keeps drawing it as you edit them: save the markdown, refresh the tab, the map re-reads from disk.

Reading a map

A focused node — the ego view on the canvas, detail and connection columns in the drawer, degree dials on each direction

The strip at the foot of the canvas holds the map's three surfaces: the Overview, a tab per type, and — when you click a card — the node itself, its detail beside its connections, split To and From. Hover a row in a type's list and its card lights on the canvas; search filters the whole map; drag to arrange, and positions are saved.

A type surface — every node of the type itemised, the hovered row glowing its card on the canvas

The markdown

Every node is a frontmatter block; every [[wikilink]] or rel: entry is an edge. One optional type: map block configures the whole thing.

---
type: map
title: Partnerships
inverse:
  works_at: employs
---

---
id: riverside-council
type: org
title: Riverside City Council
weight: lead
rel:
  employs: [dana-whitfield]
---

The anchor relationship. Everything routes through [[dana-whitfield]].

Notes that were never written for md2hd usually read fine as-is: a --- line only opens a node when what follows looks like YAML, and malformed blocks degrade to prose instead of errors.

Full syntax and guides: md2hd.com · reference · guides

Flags

The agent skill

Writing a map by hand is easy; having a coding agent write one that compiles to the graph you meant is what the bundled skill is for. The package ships writing-md2hd-maps, which teaches an agent the whole authoring language — node frontmatter, rel: and wikilink edges, the type: map block, converting an existing folder of notes into a map — and how to diagnose one that parses cleanly but draws the wrong thing: missing nodes, reversed arrows, dashed placeholders, unlabelled grey lines.

npx skills add evan-steinhilb/md2hd

Claude Code users can take it as a plugin — this repo is its own marketplace:

/plugin marketplace add evan-steinhilb/md2hd
/plugin install md2hd@md2hd

or copy skills/writing-md2hd-maps/ into your agent's skills directory — it is in the npm tarball too, so an installed md2hd carries it at node_modules/md2hd/skills/. With the skill loaded, "turn these notes into an md2hd map" produces markdown that opens as the map you asked for.

Development

This repo is self-contained: dist/ (the built visualizer) and the skill are committed, so a fresh clone can run, test, and publish with nothing else checked out. The visualizer's source lives in the md2hd app repo; npm run sync is the maintainer step that rebuilds it from a sibling ../dev checkout and refreshes dist/ before a release. npm test runs a smoke check against the packaged server.

License

MIT

md2hd (evan-steinhilb/md2hd)

Searching Database…

136 ·GitHub
Md2hd
What is this?md2hd is a CLI that turns your markdown notes into an interactive visual map: frontmatter becomes nodes, wikilinks become edges, and the result opens in your browser so you can see how everything connects.
Is this a desktop app or just a command-line tool?It's a command-line tool: you run it against markdown files and it starts a local server that renders the graph in your browser, with no account or installed app involved.
How do I get it running on my notes?Install it globally with 'npm i -g md2hd', then point it at a markdown file or folder; it opens the map in your browser automatically, and '--no-open' skips that if you'd rather open it yourself.
Do I need anything besides Node to run it?Just Node.js 18 or newer — the package requires engines node >=18 and has no other runtime dependencies listed.
Will it work on notes I didn't write specifically for md2hd?Mostly yes, but only '---' blocks that actually look like valid YAML open as nodes; anything malformed quietly degrades to plain prose instead of throwing an error, so some existing notes may just not appear as nodes.
Does any of my note data leave my machine?No — the viewer runs a server bound to 127.0.0.1, there's no account system, and the project states explicitly that there is no telemetry.
What is the bundled agent skill for?md2hd ships a skill called 'writing-md2hd-maps' that teaches a coding agent like Claude Code the full authoring syntax, so it can convert a folder of notes into a working map and diagnose ones that parse but render wrong.
Can the same map represent completely different kinds of information?Yes — a single optional type: map block in your frontmatter sets colour and layout, so the same canvas can draw an org chart, a service map, or a plot outline without md2hd needing to know what any of them mean.
Can I edit notes directly from the map view?Yes, each node's detail pane has a Code toggle that works as a live editor on the underlying file, and the map redraws as you type.
How do relationships read when you look at them on the map?Each edge speaks in the node's own voice — the same link reads 'employs' from an organisation node and 'works at' from the person node, with a chevron pointing toward the other end.
What are similar projects?open-knowledge, second-brain-os, claude-obsidian, okf-agent-memory, logseq, vault-graph, rowboat, obsidian-skills
Which topics is it in?graph, knowledge-management, knowledge-graph, note-taking, visualization, skills, browser, local-first, plugin, markdown, agent-skills, privacy
Creator
evan-steinhilb
Size
3.5 MB
Stars
136
Updated
CommitAug 26
Age
2mo
Commits · 90 Days