Lists
Bulleted, numbered, nested and task lists, including how a list holding code behaves.
- #authoring
- #markdown
- #lists
Three kinds, and the choice between them is about meaning rather than looks: a bulleted list for a set, a numbered list for a sequence, a task list for work with a state.
Bulleted
Items in no particular order. Nest one level where a point needs its own detail, and stop there; a third level is a sign the list wants to be headings.
- Discovery walks
content/and finds every directory holding aREADME.mdx.- Directory names become the route, so they must be lowercase and hyphenated.
- A directory named
homeis its category's own page rather than a note.
- Parsing reads frontmatter, headings, links and adjacent assets.
- Validation fails the build on a broken internal link or a missing asset.
Numbered
Items where the order is the content. Markdown renumbers automatically, so the
source can stay 1. throughout; writing the real numbers makes a later
insertion a diff of every line.
- Create the entry directory.
- Write
README.mdx, starting the body ath2. - Run
bun run validate:content. - Commit the directory as one change.
A procedure whose steps carry commands or explanation reads better as Steps, which keeps the numbering visible beside the code instead of letting a block push the next marker out of view.
Task lists
GitHub-style checkboxes, rendered as state rather than as controls. They are not clickable, because a page is a document and not a tracker.
- Derive entry metadata from the path and document
- Dual-theme code highlighting
- Accessible callouts, tabs and steps
- Build-time search index
- Offline bundle of the whole archive
Lists holding code
A fenced block inside an item needs to be indented to the item's text, and the panel keeps its header and copy button where it is:
-
Install the dependencies:
shell -
Check the content tree before committing:
shell
Related entries
Typography
Headings and their anchors, inline formatting, blockquotes and rules, as the document surface renders them.
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.