Writing nodes

A node is one YAML frontmatter block. The prose underneath it is that node’s notes, rendered in the detail panel.

---
id: acme
type: org
title: Acme Corp
subtitle: Municipal · 9 members
description: The anchor account. Everything downstream routes through here.
weight: lead
tags: [prospect, warm]
---

Everything below the frontmatter is the note. Headings, lists, tables and
**emphasis** all render, and bare URLs become links.

Only type and a name really matter. Everything else has a sensible fallback.

The fields md2hd reserves

Field	What it does	Falls back to
type	The category. Anything you like — it decides the colour.	note
id	How other nodes refer to it.	a slug of the title
title / name	The card’s name.	the first heading in the body, then Untitled
subtitle	One line under the title on the card.	—
description	The paragraph that opens the detail panel.	—
weight	How loudly the card is drawn.	normal
tags	Chips on the card and in the panel.	—
rel / rels / links	A map of relation to id, or a list.	—

id is slugged, so Acme Corp and acme-corp are the same node. That means you can link to [[Acme Corp]] and it resolves to id: acme-corp without you maintaining two names for one thing.

Every other key becomes a row

Anything md2hd does not reserve shows up as a labelled row in the detail panel. This is deliberate: node types are yours to invent, so the fields on them have to be too.

---
website: riversidecity.gov      # links out
email: dana@riversidecity.gov   # opens a draft
phone: +1 360 555 0142          # dials
stage: Qualified                # plain text
channels: [email, print]        # a row of chips
last_contact: 2026-05-14        # plain text
---

URLs, bare domains, email addresses and phone numbers all become clickable on their own. No markdown needed.

Values that are objects render nothing. Strings, numbers, dates, booleans and arrays all render; a nested map is skipped.

Weight

weight is a tier, not a score: five steps, independent of type. Use it to separate the handful of nodes that matter from the supporting cast.

Tier	Also accepts	Drawn as
lead	5, critical, primary, key	Full type colour, plus a halo
major	4, high	Strong stroke, faint halo
normal	3, medium, default	The default
minor	2, low	Quiet stroke, dimmed title
faint	1, background, trivial	A hairline

Geometry never changes between tiers. Cards are the same size at every weight, because the layout depends on it — a map whose card sizes shift is a map that reflows every time you edit a sentence.

Many nodes in one file

A --- line opens a new node when the next non-blank line looks like a YAML key. A --- followed by prose stays a horizontal rule.

That rule is what lets one document hold a whole map while leaving every note you wrote before md2hd existed rendering exactly as it did.

---
id: first
type: note
title: First
---

Prose for the first node.

---

That horizontal rule above is still a horizontal rule, because prose follows it.

---
id: second
type: note
title: Second
---

Anything before the first frontmatter block in a file is skipped. It is not a node, and it does not become one.

Nodes you have not written yet

Link to an id that does not exist and md2hd draws it as a dashed placeholder in grey rather than dropping the link. Nothing you reference goes missing, and the gaps in a map are visible instead of silent.

Write the block later and the placeholder fills in.