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
这是什么?md2hd 是一个把 markdown 笔记变成交互式可视化图谱的命令行工具:frontmatter 变成节点,wikilink 变成边,结果在浏览器里打开,让你看清一切之间的关联。
这是桌面应用,还是只是命令行工具?它是命令行工具:对 markdown 文件运行它,它会启动一个本地服务器,在浏览器里渲染图谱,不涉及任何账户或安装的应用。
怎么在我的笔记上跑起来?用 'npm i -g md2hd' 全局安装,然后指向一个 markdown 文件或文件夹;它会自动在浏览器里打开图谱,想自己打开的话可以用 '--no-open' 跳过。
除了 Node 还需要别的东西吗?只要 Node.js 18 或更新版本——该包声明 engines node >=18,没有列出其他运行时依赖。
对不是专门为 md2hd 写的笔记,它也能用吗?大体可以,但只有看起来确实是合法 YAML 的 '---' 块才会变成节点;格式不对的内容会静默降级成普通文本而不报错,所以有些现有笔记可能就是不会显示成节点。
我的笔记数据会离开我的电脑吗?不会——查看器运行的服务器只绑定 127.0.0.1,没有账户系统,而且项目明确声明没有任何遥测。
自带的智能体技能是干什么用的?md2hd 自带一个叫 'writing-md2hd-maps' 的技能,教 Claude Code 这类编程智能体完整的编写语法,让它能把一个笔记文件夹转换成可用的图谱,并诊断那些能解析但渲染不对的情况。
同一张图谱能表示完全不同类型的信息吗?可以——在 frontmatter 里加一个可选的 type: map 块来设置配色和布局,同一块画布就能画组织架构图、服务地图或小说情节大纲,而 md2hd 不必知道它们各自是什么意思。
能在图谱视图里直接编辑笔记吗?可以,每个节点的详情面板都有一个 Code 切换开关,可以直接对底层文件做实时编辑,图谱会随输入实时重绘。
在图谱上看关系时,它们是怎么表述的?每条边都用节点自己的口吻说话——同一条链接从组织节点看是 'employs',从人员节点看是 'works at',并有一个箭头指向另一端。
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