Markdown and MDX component reference

Nibleaf stores page bodies as Markdown strings and renders GitHub-flavored Markdown plus a documented component set. Preview source changes before publishing; syntactically valid MDX can still produce an unintended layout.

Standard Markdown

Use ATX headings (## Heading), paragraphs, emphasis, links, images, blockquotes, ordered and unordered lists, fenced code, thematic breaks, and inline code. GitHub-flavored tables, task lists, autolinks, and strikethrough are enabled.

Add a language to every fenced code block that contains code:

```bash
docker compose -f docker-compose.prod.yml up -d
```

Keep the page title in page settings rather than adding another H1 to the body. Start body sections at H2 and do not skip levels for visual styling.

Callouts

GitHub-style admonitions round-trip through the visual editor:

> [!WARNING]
> Back up Postgres and object storage before an upgrade.

Supported variants normalize to note, info, tip, check, warning, and danger. important maps to information and caution maps to danger.

Block components

The reader recognizes these component families:

Put block tags on their own lines and leave a blank line around Markdown children:

### Create a backup

Run the backup script and record the output files.

File trees are illustrations, not repository browsers. Nibleaf displays only the names written in the page body. It does not traverse the exported repository, read manifests or snapshots, fetch a path, or make a network request. API examples and related cards have the same authored-data-only boundary. Links still pass through the published-site link sanitizer and rewriter.

Tabs and code groups use a roving tab stop. Use Left/Right arrows (reversed for RTL), Home, and End to move between labels. Accordions, expandables, and folders connect each trigger to its panel with persistent accessibility IDs. File trees use nested lists rather than an incomplete ARIA tree model.

Inline components

Use <Tooltip tip="Plain-language definition">term</Tooltip> for a short definition and <Icon icon="star" ></Icon> for a curated interface icon. Do not use a tooltip for required instructions, and do not rely on an icon alone to convey meaning.

Math and diagrams

Inline and block math use dollar delimiters through KaTeX. Mermaid diagrams use a mermaid fenced block and render client-side. Always add surrounding prose that states the diagram's conclusion; the diagram must not be the only place a reader can obtain required information.

Unsupported or custom syntax

Raw scripts, event handlers, and unknown attributes are removed by the sanitizer. Custom JSX components and expressions may be preserved as source or read-only blocks, but Nibleaf cannot promise a custom runtime for them. Keep the page in Markdown mode, verify the published result, and prefer the supported component set for portable documentation.

Portability and migration

The catalog in @nibleaf/shared/documentation-components is the versioned, code-only authoring contract used by the editor, app renderer, static archives, and Git-native theme repositories. Schema version 1 is additive: existing pages need no migration. Banner supports type; dismissible is intentionally not part of the portable contract. Standalone theme repositories sanitize raw MDX with an explicit allowlist and keep customer-owned theme/component source separate from Nibleaf-owned manifests and snapshots.