Loading

Writing content

docs-builder uses CommonMark-compliant Markdown. If you know Markdown, you already know most of what you need. If not, the CommonMark project offers a 10-minute tutorial.

Standard Markdown works as you'd expect:

Text formatting

Syntax Result
**bold** bold
_italic_ italic
`code` code
~~strikethrough~~ strikethrough
H~2~O H2O
4^th^ 4th 
# Page title (h1)
## Section (h2)
### Subsection (h3)
#### Deep heading (h4)

Every page must start with exactly one # heading. This becomes the page title.

[Link text](https://example.com)
[Another page](./other-page.md)

See links for the full link syntax.

- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Another item
		
![Alt text](images/screenshot.png)
		
```python
def hello():
    print("Hello, docs!")
```

Code blocks support syntax highlighting, callout annotations, and console examples.

> We know what we are, but know not what we may be.
		
***

docs-builder supports some GitHub Flavored Markdown extensions — tables (pipe syntax) and strikethrough (~~text~~) — but not automatic URL linking or inline HTML. See the full GFM support details.

Beyond standard Markdown, docs-builder uses MyST-inspired extension points — directives and roles — to add features like callouts, tabs, diagrams, and more. These are not MyST itself; docs-builder has its own implementation of the directive and role syntax.

Directives extend Markdown with block-level features:

:::{note}
This is a callout box that stands out from regular text.
:::

How it works:

  • ::: opens and closes the directive block
  • {note} is the directive type (always in curly braces)
  • Content inside is regular Markdown

Directives can take options:

:::{image} screenshot.png
:alt: Dashboard overview
:width: 600px
:::

And can be nested by adding more colons to the outer directive:

::::{note}
Outer content

:::{tip}
Inner content
:::

::::

For the full list of available directives and detailed syntax, see the syntax guide.