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 — это CLI, превращающий ваши заметки в markdown в интерактивную визуальную карту: frontmatter становится узлами, вики-ссылки — рёбрами, а результат открывается в браузере, чтобы вы видели, как всё связано.
Это десктопное приложение или просто инструмент командной строки?Это инструмент командной строки: вы запускаете его на markdown-файлах, а он поднимает локальный сервер, который рисует граф в вашем браузере — без аккаунтов и устанавливаемых приложений.
Как запустить его на своих заметках?Установите глобально командой 'npm i -g md2hd', затем укажите markdown-файл или папку; карта откроется в браузере автоматически, а '--no-open' пропускает это, если предпочитаете открыть её сами.
Нужно ли что-то, кроме Node, чтобы его запустить?Только Node.js 18 или новее — пакет требует engines node >=18 и других runtime-зависимостей не заявляет.
Будет ли он работать с заметками, которые я не писал специально для md2hd?В основном да, но узлами открываются только блоки '---', которые действительно похожи на валидный YAML; всё неаккуратное тихо превращается в обычный текст вместо ошибки, так что часть существующих заметок может просто не появиться узлами.
Данные моих заметок покидают мою машину?Нет — просмотрщик поднимает сервер, привязанный к 127.0.0.1, системы аккаунтов нет, и проект прямо заявляет об отсутствии телеметрии.
Для чего нужен идущий в комплекте агентский скилл?md2hd поставляет скилл 'writing-md2hd-maps', который обучает кодинг-агента вроде Claude Code полному синтаксису создания карт, чтобы тот мог превратить папку заметок в рабочую карту и разбираться с теми, что парсятся, но рисуются неправильно.
Может ли одна карта представлять совершенно разные виды информации?Да — один опциональный блок type: map во frontmatter задаёт цвет и раскладку, так что один и тот же холст может нарисовать оргструктуру, карту сервисов или план сюжета, и 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