md2hd
Markdown, mapped - the MD2HD CLI. Pull the repo, tell your agent to create an MD2HD map, visually comprehend complex topics and relationships.
What is it?
What it is
md2hd is a local, zero‑telemetry tool that turns Markdown files into an interactive graph map. Each Markdown frontmatter block becomes a node, and wikilinks or `rel:` entries become edges, allowing users to visualize organizational structures, service maps, or narrative outlines directly from their existing notes.
Why it exists
It fills the gap between written material and the mental picture of how that material relates. By keeping everything on the local machine, it respects privacy, lets users define custom node types, and updates the map live as files change, making it a lightweight, privacy‑first way to see the topology of knowledge.
Who should use it
Knowledge workers, researchers, writers, and developers who maintain markdown notes and want to visualize relationships between concepts, people, or entities. Ideal for those who value local-first tools, need to map organizational structures, plot outlines, or service architectures, and prefer editing markdown while seeing live graph updates in the browser.
Who should avoid it
Users who require real-time collaboration features, cloud syncing, or multi-user editing capabilities. Not suitable for those who need complex database-backed knowledge graphs or extensive plugin ecosystems beyond the bundled agent skill.
Stars over time
No change stars in the last 1 day
How it works
A quick walkthrough in plain English
How md2hd works in 4 steps
Step 1 of 4
Something triggers the flow
A schedule, webhook, or manual click tells md2hd to start.
Features
Advantages
- Privacy: everything stays on your machine, no cloud services
- Flexibility: same engine can model org charts, service topologies, story outlines, etc., just by defining types
- Real‑time feedback: edit markdown and instantly see the map update
- Powerful navigation: focus mode and degree dials let you explore relationships at any depth
- Dual editing: you can edit the map UI and the underlying markdown interchangeably
- Easy adoption: simple CLI (`npx md2hd notes/`) and clear markdown syntax
- AI‑assisted authoring: the bundled skill lets agents write correct md2hd maps automatically
- Persistent layout: drag‑and‑drop positions are saved across sessions
Disadvantages
- Learning curve: you need to understand frontmatter YAML and the custom link syntax
- UI is web‑based; not ideal for pure terminal workflows
- No built‑in diff/merge tools for map layout; layout changes are stored in markdown frontmatter
- Performance may degrade with very large note collections (hundreds of nodes)
- The agent skill is separate and requires extra setup for some AI platforms
- Limited to markdown files; other note formats would need conversion
- No native desktop app; relies on a browser and Node.js server
Installation
native
npx md2hd notes/ or npx md2hd map.md; or install globally: npm i -g md2hd
FAQ
How do I launch md2hd to visualize a folder of Markdown notes?
Run `npx md2hd <folder>` (e.g., `npx md2hd notes/`). The tool starts a local server, opens your browser, and draws a map from all Markdown files in the folder.
Can I view a single Markdown file as a map?
Yes. Use `npx md2hd <file>` (e.g., `npx md2hd map.md`). The file’s frontmatter and wikilinks are parsed into nodes and edges, and the map is displayed in your browser.
What is the role of frontmatter and wikilinks in md2hd?
Each node is defined by a YAML frontmatter block (`---` … `---`). Wikilinks (`[[link]]`) or `rel:` entries inside the frontmatter create edges between nodes, forming the graph that md2hd visualizes.
How can I customize the map’s type and inverse relationships?
Add a top‑level `type: map` block in any Markdown file. Inside it you can set properties like `title`, `inverse` (e.g., `works_at: employs`), and other configuration options that affect the entire map.
How do I use the bundled agent skill to generate a map from notes?
Install the skill with `npx skills add evan-steinhilb/md2hd`. Once loaded, you can ask the agent to "turn these notes into an md2hd map", and it will produce Markdown that, when opened with md2hd, displays the desired graph.
Featured in Videos
YouTube tutorials and walkthroughs for md2hd
Alternatives
Similar projects ranked by category, topics, and text overlap.
