Wiki-links.

[[page-name]] · Obsidian syntax

Wiki-links are how pages reference each other. Resolution is by basename only — which is why basenames must be unique across the whole tree. Render in Obsidian, scan with lint.py, follow when reading.

Syntax

# basic link — render and follow by basename
[[checkout-api]]

# alias — display different text
[[checkout-api|the checkout service]]

# inside frontmatter — same resolution
services: [checkout-api, payments-db]

# in body prose — link the FIRST mention only
[[connection-pool-exhaustion]] surfaced again on 2026-04-12;
pool exhaustion remained the dominant pattern after that.

Rules

1. Syntax is [[page-name]] or [[page-name|display text]]. The page-name is the file basename without .md.
2. Link the first mention of any other entity on a page. Subsequent mentions stay plain text.
3. Frontmatter list values are wiki-links too — services: [checkout-api] resolves to wiki/services/checkout-api.md.
4. Basenames are unique across the entire wiki tree. Two pages cannot share one — tools/lint.py enforces this because collisions break resolution.
5. If a linked page doesn't exist, create a stub. Never leave a dangling link.
6. Links are case-sensitive on the filesystem but Obsidian normalises — pick one casing convention and stick to it (we use kebab-case).

Why basename-only resolution

Obsidian and the lint tool both resolve [[checkout-api]] by scanning the whole wiki/ tree for a file named checkout-api.md. This lets pages move between folders without breaking links — but it requires every basename to be globally unique. If you ever need two pages with the same logical name (rare), disambiguate the slug at file-rename time, not by adding folder prefixes to the link.