When the map is wrong

Nearly every surprise in md2hd comes from one of six causes. Each has a tell.

A file produced no nodes

Tell: the app reports no frontmatter block, skipped.

md2hd only reads YAML frontmatter. A file with none is not a node and does not become one. Anything before the first frontmatter block in a file is also skipped.

Check that the opening --- is on its own line, at the very start of the block, and that a YAML key follows it. A --- followed by prose is treated as a horizontal rule, on purpose.

A node is missing from the middle of a file

Tell: the first node in a file appears, later ones do not.

A --- only opens a new node when the next non-blank line looks like a YAML key — roughly, word: followed by a space or end of line. If your second block starts with a comment, an indented line, or a key containing a character outside A–Z a–z 0–9 _ . -, the separator reads as a horizontal rule instead.

A card is grey and dashed

That is an unresolved node: something links to that id, but no block defines it.

This is not an error. Links to things you have not written yet are kept deliberately, so a gap in the map is visible rather than silent. Write the block and it fills in.

If you did write it, the id does not match. Ids are slugged — lowercased, punctuation dropped, spaces and underscores turned into hyphens — so check that both ends slug to the same string.

Malformed YAML silently empties a block

Tell: a node appears with the title Untitled and none of its fields.

If the frontmatter does not parse, md2hd treats the block as empty rather than dropping it, and the body still renders. The usual causes are a value containing a colon that is not quoted, and inconsistent indentation.

subtitle: Municipal: 9 members     # breaks
subtitle: 'Municipal: 9 members'   # fine

Wikilinks in frontmatter need quoting too, because [ starts a YAML flow sequence:

works_at: '[[acme]]'

Two lines between the same pair

You wrote the relationship from both ends with wordings md2hd cannot see are the same fact.

It flips _by labels automatically and collapses anything that then coincides on a crude stem, so owns and owned fold together. Where the two sides use genuinely different words, declare the pair:

---
type: map
inverse:
  works_at: employs
---

If the relation has no direction at all — knows, met, partner — list it under symmetric: instead, or write it from both sides and let it fold itself.

A relation reads backwards

A label ending in _by is always stored pointing the other way, because passive voice always points backwards. owned_by: dana on the portal is the same edge as owns: portal on Dana, and md2hd will draw it from Dana.

If a label of yours legitimately ends in by and is not passive, rename it. The rule has no vocabulary list and no exceptions.

A duplicate id

Tell: the app warns duplicate id … — later copy merged.

Two blocks resolved to the same id, usually because both fell back to a slug of the same title. Set id: explicitly on at least one of them.

Nothing loads at all

md2hd draws in the browser and needs JavaScript. If the canvas stays on “Opening the canvas…”, check that scripts are not blocked for this site.

If a map that used to be there has gone, the browser’s site data for md2hd was cleared — that is where maps live. Your original markdown files are untouched; reimport the folder.

Still wrong

The behaviours md2hd deliberately does not have are written down rather than left to be discovered. If what you are seeing is not on that list and not on this page, open an issue with the smallest markdown that reproduces it.