writing-md2hd-maps

Writing markdown for md2hd

md2hd turns a folder of markdown into a graph. Every YAML frontmatter block is a node, rel: entries and [[wikilinks]] are edges, the prose under a block is that node's notes, and one block with type: map configures the whole map.

The governing fact: the parser never rejects anything. Malformed YAML, a misspelled setting, a block that never opened — all of it parses to something and draws something. There is no error state. Every mistake below is silent, so the job is not "does it parse" but "does it draw what I meant".

Everything in this document was verified against the parser (src/lib/parse.ts in the md2hd repo). Where a friendlier user guide disagrees, this wins.

The shape of a file

One file may hold the whole map. A --- line opens a new block, and the body runs until the next line that opens one.

---
type: map
title: Partnerships
---

---
id: riverside-council
type: org
title: Riverside City Council
---

Prose here is this node's notes.

---
id: dana-whitfield
type: person
title: Dana Whitfield
---

And this is Dana's.

• Blank lines around blocks are optional. Tight --- runs parse identically.
• Prose before the first block is dropped. It belongs to no node.
• A --- followed by prose stays a horizontal rule and remains inside the current node's body. Only a --- whose next non-blank line looks like a YAML key opens a block, which is why existing notes full of rules still work.
• *** and ___ never open a block.

The rule that decides it

The line after --- must match /^[A-Za-z_][\w .-]*\s*:(\s|$)/.