Article Field Manual

Navigation#

The rail on a wide screen lists every section and the headings under it. The same list sits in a disclosure when the column is narrow. A brass mark tracks how far the page has moved.

Contents rail#

Scroll the page and the active row follows the heading nearest the top. The number on the row matches the number above the section.

Heading anchors#

Each section heading keeps a quiet # at the end of the line. It appears on hover or when the link is focused, and it points at that heading.

Section pager#

The pager closes a section with the previous page, the next page, or both.

Inline elements#

A sentence can hold tallyVotes() for a name, Ctrl + K for a shortcut, a single marked phrase, an API with its expansion, and a link such as the archive. A note stays out of the line.^[1]

Status badges#

Mark the state of a feature inline: Stable Beta Deprecated

Callouts#

Four rails. Note is the default. Tip keeps a patina edge. Warning uses copper on the left edge only. Danger frames the whole block in copper.

Code snippets#

Fenced code still renders. The blocks below are the same well, with a file name, a language, and a copy control.

Basic block#

export const config = {
  name: "field-manual",
  draft: false,
}

Line numbers and highlights#

import queue def work(jobs):    while not jobs.empty():        item = jobs.get()        handle(item)        jobs.task_done()

Tabbed snippets#

const res = await fetch("/api/items?limit=10");
const data = await res.json();

import requests
res = requests.get("/api/items", params={"limit": 10})
data = res.json()

curl -s "/api/items?limit=10"

Diff#

 function handler(req) {-  return req.body;+  return req.body ?? {}; }

Terminal#

The copy control keeps the commands and drops the prompt and the replies.

$ npm run typecheckdone$ npm run build1 warning: unused export "draft"

Code with explanation#

function find(list, test) {
  for (const item of list) {
    if (test(item)) return item;
  }
  return null;
}

Graph containers#

Pictures in this section are drawn in the page. The other tab holds a plain reading of the same edges. No diagram host is called.

Flowchart#

Page -> Check
Check -> Store

Sequence#

Page -> Store: read
Store -> Page: row

State#

Idle -> Run
Run -> Done

Class diagram#

Article
+-- Section
+-- Figure

Tree containers#

Collapsible file tree#

Folders open and close. A wash marks the entry file. Added and removed files keep their own tone.

Plain text tree#

components/mdx
+-- CodeBlock.tsx
+-- Contents.tsx
|   +-- rail
+-- Figure.tsx

Media#

Figure#

Image gallery#

Open a plate, then move with the buttons or the arrow keys.

Before and after#

BeforeAfter

Video#

Data#

Table#

Comparison#

Bar chart#

Key figures#

Explaining functionality#

Steps#

1. Install the package

   The lockfile stays in the repo. Install from that file.

   terminalbashCopy

   $ npm install

2. Write the config

   One file, next to the pages, with the name the card will show.

3. Run the check

   Typecheck, then build, before the page is called done.

API endpoint#

{
  "name": "Field manual",
  "tags": ["reference", "mdx"]
}

{
  "id": "itm_42",
  "name": "Field manual"
}

{
  "error": "name is required"
}

Content tabs#

Keyboard shortcuts#

Pros and cons#

Checklist#

• Read the header before the body
• Confirm the rail matches the headings
• Open the notes only when a sentence points there

Definition list#

Rail

The contents column. It lists sections and follows the one in view.

Well

A recessed frame for code, with a file name and a copy control.

Plate

One image with a caption. It can span the column or sit narrow.

Timeline#

1. v1.2.0Rail addedSections and subheadings share one list, with a progress mark.
2. v1.1.0Plate removedThe page is no longer one filled container.
3. v1.0.0First benchHeader, callouts, code, and figures.

Formula#

Collapsible notes#

Quotes and references#

Blockquote#

A project page is still a web page. Give each block a frame, and leave air between the sections.

Workshop notes, 2026

Pull quote#

The page is the width of the site. The blocks are what change.

Link card#

Divider#