Links
Internal routes, heading anchors, adjacent files and external destinations, and which of them the build checks.
- #authoring
- #markdown
- #links
An archive is worth keeping only if its cross-references stay true, so the build resolves every link an entry writes. A link to a route, an anchor or an adjacent file that does not exist fails the build and names the file and the line, instead of breaking silently for a reader a year later.
The four kinds
- Internal route. A canonical path under
/stash/, routed client-side: useDebounce. - Heading anchor. A section of another entry, checked against that document's heading slugs: Command menu keyboard navigation.
- In-document anchor. A section of this page: the four kinds.
- External. Anything off the site, which opens in a new tab with the usual
relguards: MDN.
Relative paths
A relative Markdown path is resolved against the entry's own directory, so sibling notes can be reached without repeating the domain: ../tables. It is rewritten to the canonical route when the document is compiled, and validated like any other internal link.
Adjacent files
A path beginning ./ points at a file in the entry's own directory, which is
served as-is rather than rendered. A link whose target is ./use-debounce.ts
resolves to the file beside the document. Such a link only works from that one
document, so a file worth referring to from elsewhere is quoted rather than
linked. See Adjacent files.
Writing them
Prefer a link whose text says where it goes, because the text is what a screen reader announces out of context and what a reader scans for. "See how code panels are headed" carries its destination; "see here" does not.
When the next thing to read matters more than a sentence allows, give it a link card instead of an inline link.
Related entries
Typography
Headings and their anchors, inline formatting, blockquotes and rules, as the document surface renders them.
Lists
Bulleted, numbered, nested and task lists, including how a list holding code behaves.
Tables
GFM tables, column alignment, and what happens to a wide table on a narrow screen.