Skip to content
ArcadiaDesign
At 1280 wide, drawn to fit. Press ⌘K inside it to search.

TSX

Every product's docs stand in one shell: the bar with Arcadia, the product's name and Docs, the tree of pages beside the page, On this page in the rail, and the search. A product hands it what is its own and nothing else: its name, its tree (nav, a members row marked members), its search index (index, the address of its JSON or the entries), where its pages live (base, /docs by default), the page drawn (path), a way to go (navigate, else a link loads its page), whether the reader is signed in (signedIn) and Arcadia's address (hosts).

A page is a DocsArticle: its facts, its Markdown in body and a reader, the product's Markdown parser. The kit holds how every element of the body looks, the {#id} anchors on its headings and the > [!NOTE] alerts, and no parser: react-markdown with remark-gfm is one, passed as { Markdown, plugins: [remarkGfm] }. The feedback line and the help address are the product's, feedback and contact, each left out when not given.

Static pages

The shell and the article render to plain HTML at build time, and no module of the docs needs a browser to load.

TSX

Each page renders whole with React's server renderer. What needs a browser (the search, the drawer, the theme, the rail, Copy page, the copy buttons and the feedback line) comes alive when the page hydrates the same tree: write each page's props beside its HTML, and hand hydrateRoot the same props and the same reader. The search reads its index on the first search.

Examples

Narrow

Under 900 wide the tree folds into a drawer that the bar's first button opens, and the search into a glyph.

The bar is the banner, the tree a region named Documentation with each group named by its label, and the page sits in main. The first stop is a skip link to the page's title; after a page changes, focus moves to the new title so a reader hears it. The current row and the trail's last level carry aria-current="page".

⌘K, or / outside a field, opens the search: a dialog named Search the docs whose field is a combobox over a listbox of results. The arrow keys move the highlight, Return opens the row, and Escape closes it and gives focus back. Under 900 wide the tree is a modal drawer: focus starts on the current row and stays inside, Escape and the scrim close it, and focus goes back to its button.

DocsShell

namerequired
string
The product's name, as its bar says it: the trail's middle level, and the key its recent pages are kept under.
base
stringDefault "/docs"
Where its pages live: the trail's last level, and the only paths drawn in place.
navrequired
DocsGroup[]
Its tree of pages: the groups and their rows, in order.
indexrequired
DocsIndex
Its search index: the address of its JSON, read on the first search, or the entries.
suggested
string[]
The pages search offers before anything is typed; the tree's first four by default.
pathrequired
string
The page drawn, its address's path.
navigate
(href: string) => void
Draws a page of the docs in place (a router's push); without it, a link loads its page.
signedIn
booleanDefault false
Members rows show only to a reader who is signed in, and on a members page itself.
hostsrequired
{ arcadia: string; home?: string }
Where the mark leads (Arcadia's home) and the product's name (its home, / by default).
pinnedTheme
"light" | "dark" | null
A theme the link pins (?theme=), previewed without touching the stored choice.
pinnedMotion
"on" | null
Reduced motion the link pins (?rm=1), the same way.

slugrequired
string
pathrequired
string
markdownrequired
string
The page's Markdown twin.
sectionrequired
string
titlerequired
string
descriptionrequired
string
bodyrequired
string
referencerequired
boolean
A reference page: the rail lists h2 only.
relatedrequired
ArticleLink[]
prev
{ href: string; title: string; description?: string }
next
{ href: string; title: string; description?: string }
readerrequired
{ Markdown: (props: DocsReaderProps) => ReactNode; plugins?: readonly unknown[] }
Reads body: the product's Markdown parser, drawing the kit's elements. With react-markdown and remark-gfm, { Markdown, plugins: [remarkGfm] }.
feedback
ReactNode
The feedback line: the product's PageFeedback, sending where it sends. None, no line.
contact
string
Where help and feedback go, an email address. None, no line.