The language

A project is a folder of markdown files. Every YAML frontmatter block becomes a node on the canvas; the prose under it becomes that node’s notes.

A node

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

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

Only type and a name really matter. id falls back to a slug of the title, title falls back to the first heading, type falls back to note. subtitle sits under the title on the card; description is the paragraph that opens the detail panel.

Weight

Not every node deserves the same amount of attention. weight says how loudly one is drawn — five tiers, named or numbered 1 to 5, independent of type. A lead node holds its type colour at full strength and picks up a faint halo; a faint one recedes to a hairline. Leave it out and a node sits at normal.

---
weight: lead      # or 5 — also: major/4, normal/3, minor/2, faint/1
---

Weight changes nothing about the graph itself, only how hard the card pushes back at you. Use it to separate the handful of nodes that matter from the supporting cast.

Any other field

Every key you add that md2hd does not already understand shows up as a labelled row in the panel. Invent whatever the map needs.

---
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
---

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

Many nodes in one file

A --- line opens a new node when the next line is a YAML key. A --- followed by prose is still just a horizontal rule, so existing notes keep rendering the way they always did.

Links

Four ways to connect nodes. Use whichever fits how you already write.

---
rel:                          # a map of relation -> id, or list of ids
  employs: [dana, marcus]
  runs: records-portal
works_at: "[[acme]]"          # any frontmatter value that is a wikilink
---

Talked to [[dana]] about it.  # bare wikilink -> an untitled "mentions" link
owns:: [[depot]]              # inline field -> a link labelled "owns"

Link to something that does not exist yet and it appears as a dashed placeholder, so nothing you reference goes missing.

One relationship, one line

You will write the same fact from both ends — dana owns portal in one note and portal owned_by dana in the other. md2hd turns every link to face the same way before drawing it, so that stays one line on the canvas:

• Passive voice flips. Any label ending in _by is the same relationship seen backwards, so owned_by, attended_by and run_by are stored as owns, attended and run pointing the other way.
• Declared pairs flip. inverse: in the map config handles the rest, where the two sides use different words.
• Bare wikilinks defer. A [[link]] between two nodes a named relation already connects adds nothing, so it is dropped.

---
type: map
inverse:
  works_at: employs      # "X works_at Y" is "Y employs X"
  met: attended_by
---

Two voices, one direction

A relationship runs one way but reads differently from each end: an organisation employs a person, and that person works at the organisation. Select a node and every link states itself in that node’s voice, with the arrow pointing at the node on the other end — the same link is → employs from the organisation and → works at from the person.

On the canvas only the voice you are reading from appears, so a link is one line with one label. The detail panel carries both: each connection heading shows this node’s wording and, beside it, the other node’s.

md2hd learns the second voice from your notes: either you wrote both sides (employs: in one, works_at: in the other), or you declared the pair under inverse:. Where only one wording exists it keeps that one and aims the chevron inward instead, meaning “something informs this”.

Some relations read the same from both ends and have no direction at all. List them under symmetric: — or just write them from both sides and they fold themselves together. They draw without an arrowhead and carry a chevron at each end, pointing at both nodes.

---
type: map
symmetric: [knows, met, partner]
---

Configuring the map

One block with type: map sets the project’s title, rank direction, and the colour and label for each node type. Types you leave out are assigned a colour from the built-in palette, in order, so a map needs no colours at all to read clearly.

---
type: map
title: Partnerships
layout: TB                    # TB (default) or LR
inverse:                      # relations that mean the same thing both ways
  works_at: employs
symmetric: [knows]            # relations with no direction at all
types:
  org: { label: Organization, color: "#4A9BFF" }
  person: { label: Person, color: "#3FC8D4" }
---

On the canvas

Click a node and the map re-forms around it: what points at it on the left, what it points at on the right, everything else out of the way. Click the background to put the map back. The ◎ button in the toolbar turns that off if you would rather the map held still.

Hover lights up everything within two links. Search filters the whole map. Type filters hide a category at once. Drag to arrange — positions are saved. Open Source in the detail panel to edit a file and the map redraws as you type.

Every field

On a node

Field	Effect
type	Which category it belongs to. Anything you like. Defaults to note.
id	How other nodes refer to it. Defaults to a slug of the title.
title / name	The card’s name. Defaults to the first heading in the body.
subtitle	One line under the title on the card.
description	The paragraph that opens the detail panel.
weight	lead major normal minor faint, or 1–5. Defaults to normal.
tags	Chips on the card and in the panel.
rel / rels / links	A map of relation to id, or a list.
anything else	A labelled row in the detail panel.

On the map block (type: map)

Field	Effect
title	The map’s name.
layout	TB (default) or LR.
types	{ label, color } per node type. Unlisted types are assigned a colour.
inverse	works_at: employs — one relation is the other seen backwards.
symmetric	Relations that read the same both ways: [knows, met].

In the body

Syntax	Effect
[[target]]	An untyped mentions link.
[[target|alias]]	The same, displayed as alias.
owns:: [[target]]	A link labelled owns.
Anything else	Markdown, rendered in the detail panel. Bare URLs autolink.