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|$)/.

A block that fails to open is not an error — the --- becomes a rule and the entire node silently disappears from the map. id:acme with no space is the single easiest way to lose a node.

Write it in this order

1. The map block. Exactly one, and it is configuration — it never draws as a node and never links to anything.

---
type: map
title: Partnerships
layout: LR
types:
  org: { label: Organization, color: "#4A9BFF" }
  person: "#3FC8D4"
inverse:
  works_at: employs
symmetric: [knows]
---

2. Nodes with an explicit id and title. Both have fallbacks and both fallbacks surprise people (see below). Two extra lines removes the whole class.

3. Name every relationship. Use rel: for structure. A bare [[wikilink]] draws an unlabelled grey mentions line — use it only when you mean "this came up here". A map full of them says nothing.

4. Declare inverse: and symmetric: deliberately. Both are global per label, not per node pair. See the normalisation section — this is the most common way to get a graph that is subtly wrong.

5. Read back every link as drawn, not just "it parsed". The normalisation pass rewrites directions and merges edges before anything appears.

Node fields

Every key is optional; a block with empty frontmatter still becomes a node.

title falling back to any heading — not just a leading one — means a node whose body starts with prose and has ## Open questions halfway down will be named "Open questions". Set title: on anything containing headings.

Two nodes with neither title: nor a heading both become Untitled and both slug to the same id.

Weight

Absent or empty → 3. A number (or numeric string) is rounded and clamped to 1–5. Otherwise a case-insensitive word lookup, and any unrecognised word silently becomes 3.

Weight affects drawing only, never the graph.

ids and slugging

slug() runs on id, on the title fallback, and on both ends of every link — which is why [[Acme Corp]] finds id: acme-corp.

trim → lowercase → delete everything except [A-Za-z0-9_ -] → collapse [\s_]+ to "-" → trim "-"

So id: my_node, [[my-node]] and [[my_node]] are all the same node. Give accented or non-Latin titles an explicit ASCII id:.

Duplicate ids do not merge, despite a warning that says "later copy merged". Both nodes draw; only the second is reachable by link. Treat it as an error.

The map block

Those five keys are the only ones read. Anything else is never looked at. direction:, colors:, rankdir: and palette: are all valid YAML that does absolutely nothing — this is the most common authoring mistake, because the names are so plausible.

Types you omit get a palette colour in encounter order, so a map needs no colours at all to read clearly.

Two map blocks do not merge. The last one replaces the config wholesale, so a layout: LR in the first is lost if the second omits it. Keep exactly one.

The four ways to link

1. rel: / rels: / links:

rel:
  employs: [dana, marcus]      # relation -> id, or list of ids
  runs: records-portal
rel:
  - employs: dana              # list of single-key maps also works
rel: [dana, marcus]            # list of bare scalars -> label is "links"

2. Any non-reserved frontmatter key whose value is a wikilink

works_at: "[[acme]]"           # edge labelled "works_at"
attendees: ["[[dana]]", "[[marcus]]"]

Reserved keys are skipped: id type title name subtitle description weight tags rel rels links layout types inverse symmetric. A wikilink inside description: makes no edge.

3. Inline fields in the body — /(?:^|\s)([A-Za-z][\w-]*)::\s*(.+)$/gm

owns:: [[depot]]                 label "owns"
mid sentence owns:: [[depot]]    also matches — preceded by a space
nope-owns:: [[d]]                matches; label is "nope-owns" (hyphens legal)
1bad:: [[d]]                     no match — must start with a letter

4. Bare wikilinks in the body → an untyped mentions edge, unless an inline field on the same node already claimed that target.

[[target|alias]] links to target; the alias only changes displayed text.

Self-links are dropped — a node with rel: { knows: <its own id> } produces no edge at all.

What happens to your links before anything is drawn

This pass rewrites what you wrote. It is where authored text stops matching the canvas, and where most "the graph is wrong but it parsed" bugs live.