Fix a map that draws wrong

Start with the visible symptom.

No cards were found

Each card needs YAML frontmatter. Check that:

1. the opening --- is on its own line;
2. a YAML key such as type: follows it;
3. the block closes with another --- line.

Text before the first card block is ignored. A --- followed by prose stays a Markdown horizontal rule.

A later card in the file is missing

A separator only starts a card when the next non-blank line looks like a YAML key. A comment, indented line, or malformed key directly after --- prevents the new block from opening.

A card is gray and dashed

Another card links to this ID, but no block defines it. Add the card or correct the target ID.

IDs are lowercased, punctuation is removed, and spaces or underscores become hyphens. Check that both ends resolve to the same slug.

A card is titled Untitled

The frontmatter did not parse. Common causes are an unquoted colon or uneven indentation:

subtitle: 'Municipal: 9 members'
works_at: '[[acme]]'

Quote frontmatter wikilinks because [ has YAML syntax of its own.

Two lines connect the same cards

The same fact was written from both ends with labels md2hd could not match. Declare the two voices in the map block:

type: map
inverse:
  works_at: employs

For relationships with no direction, use:

symmetric: [knows, met, partner]

A connection points backwards

Labels ending in _by reverse automatically. owned_by: dana on a portal draws from Dana to the portal as owned.

For other opposite wordings, add the pair under inverse:. If your label ends in _by but is not passive, rename it.

A duplicate ID warning appears

Two blocks resolved to the same ID, often because they have the same title. Add an explicit, unique id: to at least one.

md2hd does not open

md2hd needs JavaScript to draw the map. If the page remains on “Opening md2hd…”, allow scripts for the site and reload.

If a hosted map is missing, confirm that you opened the correct account and workspace. Imported source files on your computer are never changed, so you can import them again.

Still wrong

Check the markdown reference and the documented product limits. If neither explains the result, open an issue with the smallest markdown file that reproduces it.