Typography
Headings and their anchors, inline formatting, blockquotes and rules, as the document surface renders them.
- #authoring
- #markdown
- #typography
The prose surface is plain Markdown. Measure, leading and contrast are set once for the whole document, so an entry reads the same whichever note it is, and an author never has to think about spacing.
Headings and anchors
Headings carry the document's structure, which is also its table of contents and its link targets. Every heading is slugged and gets a permalink that appears on hover, so a section can be pointed at from anywhere.
The document's opening # Heading is a special case: the route prints the
entry's title above the body already, so a leading h1 is removed before
rendering rather than shown twice. Keep writing it, because it is what makes
the file readable on disk and on GitHub, and start the body's own structure at
h2.
A third-level heading
Nesting past h3 is rarely worth it; a note that needs an h4 is usually two
notes.
A fourth-level heading
Four levels are styled, and the table of contents follows h2 and h3.
Inline formatting
- Bold for the term a paragraph is about:
**bold**. - Italic for emphasis and for words used as words:
*italic*. - Both where a sentence genuinely needs it, which is seldom.
Strikethroughfor a superseded claim kept on purpose:~~text~~.Inline codefor anything typed literally:useMemo(),Record<string, unknown>,process.env.NODE_ENV.- Keys render as keys: Ctrl + K. See Keyboard keys.
Blockquotes
A blockquote is for someone else's words. It takes an accent border and muted type, and nests when the quotation does.
Simplicity is prerequisite for reliability.
Edsger W. Dijkstra
The rule held for the first year.
Then the index grew past memory and it stopped holding.
Something that is not a quotation, such as a warning, an aside or a caveat, belongs in a callout instead, where a screen reader announces it as a notice.
Rules
A thematic break separates sections that are genuinely unrelated:
Used between every heading it becomes noise, since headings already separate.
Related entries
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.
Links
Internal routes, heading anchors, adjacent files and external destinations, and which of them the build checks.