The design documentation is written in Markdown with some extended features and lives in design/. mdBook builds it into a book, with the output written to .design_html/.
Note
mdBook processes the Markdown source through preprocessors and a renderer (backend), producing a static HTML site by default.
SUMMARY.md defines the structure and page hierarchy of the book. Every page must be listed there to appear in the rendered output.
Add the page to SUMMARY.md first. When mdBook is running in watch mode (which it should be during development), it will automatically create a stub file at the referenced path --- edit that file directly, so you can be certain you are working in the correct location.
Tip
- The same watch behavior must be accounted for when deleting or moving/renaming pages, but the order of operations differs:
- Deleting: Remove the reference from
SUMMARY.mdfirst, then delete the file. Deleting the file first will cause mdBook to recreate it as a stub. - Moving/renaming: Move or rename the file first, then update
SUMMARY.mdand clean up any stub files/folders mdBook created at the old path.
- Deleting: Remove the reference from
- If no stub appears after adding a reference to
SUMMARY.md, raise the issue --- the developer may have forgotten to runmdbook serve.
- Unordered lists should use
-as the marker.-
Sub-lists should be indented with 2 spaces...
...and multi-line items should be indented with 3 spaces for visual consistency.
-
- Headings should only be followed by a blank line if they mark a section containing independent items, e.g. a list of functions. If a heading's subordinate content (including sub-headings) is uniquely tied to the heading, e.g. information pertaining to a single function, then no blank line should be used.
mdBook supports some features beyond standard Markdown. This is a non-exhaustive list of features we may want to use in the documentation.
Admonitions are callout blocks that render with a distinct visual style. Use them to highlight important information. While visually distinct, they are functionally blockquotes and their content can be formatted with Markdown features.
> [!NOTE]
> This is a note.The following types are available:
[!NOTE][!TIP][!IMPORTANT][!WARNING][!CAUTION]
External files can be embedded using {{#include}}. Paths are relative to the current document. Works inside fenced code blocks, including (explicit) syntax highlighting. Optionally, only certain line numbers (1-indexed) can be included by appending :line or :start:end to the path.
Example:
```toml
\{{#include ../book.toml:1:3}}
```
mdBook automatically converts ASCII punctuation sequences to typographic equivalents. Use these instead of Unicode characters directly --- this applies project-wide to all documentation.
| Write | Renders as |
|---|---|
-- |
-- (en dash) |
--- |
--- (em dash) |
... |
... (ellipsis) |
Definition lists can be used for glossary entries and term definitions.
term
: Definition of the term. Text can span
multiple lines.
: If more than one definition is given, they render as a numbered list.Headings can be given a custom ID for stable cross-references. This is useful when multiple sections share the same name --- rather than relying on auto-generated suffixes like #usage-2, an explicit ID can be set on the anchor point as needed.
## Usage { #unique-usage }In the sidebar, headings (where level = number of # characters) render as follows:
- Level 1: Reserved for the page title. Does not appear as a sidebar navigation entry.
- Level 2: Always visible in the sidebar.
- Level 3: Visible with a collapse toggle --- content can be expanded.
- Level 4 and deeper: Hidden inside the level 3 toggle until expanded.
Tip
Structure documents with this in mind --- important navigational entry points should be at level 2 or 3.