MyST Markdown¶

Write Sphinx documentation in Markdown with full access to directives and roles.

Lumina works with both reStructuredText and MyST Markdown. We recommend MyST for a more natural writing experience.

Setup¶

uv (recommended)

uv add myst-parser

pip

pip install myst-parser

conf.py¶

extensions = ["myst_parser"]

myst_enable_extensions = [
    "colon_fence",     # Use ::: for directives instead of ```
    "dollarmath",      # $inline$ and $$display$$ LaTeX math
    "amsmath",         # Multi-line equation environments
    "tasklist",        # - [x] checkbox task lists
    "deflist",         # Definition lists (Term\n: Definition)
    "fieldlist",       # :Key: Value metadata lists
    "substitution",    # {{variable}} template replacements
]

Writing in MyST¶

Write your docs in .md files instead of .rst:

# My Page Title

This is a paragraph with **bold** and `code`.

:::{note}
Admonitions use the colon fence syntax.
:::

Colon Fence Syntax¶

The colon_fence extension gives you a cleaner syntax for directives.

Colon fence (recommended):

:::{note}
This is cleaner and easier to type.
:::

Backtick fence (standard):

```{note}
This also works, but nesting gets awkward.
```

The colon syntax is especially helpful for nested directives — just add more colons for each level:

::::{warning}
Outer admonition.

:::{tip}
Inner admonition.
:::
::::

Substitutions¶

Define reusable variables in conf.py and use them across pages:

conf.py¶

myst_substitutions = {
    "project_name": "My Project",
    "version": "1.0.0",
}

Use them in any .md file:

Welcome to {{project_name}} version {{version}}.

Available Extensions¶

Extension	Description
`colon_fence`	Use `:::` for directives instead of backtick fences. Cleaner nesting.
`dollarmath`	$inline$ and `$$display$$` LaTeX math syntax.
`amsmath`	Multi-line equation environments like `\begin{aligned}`.
`tasklist`	`- [x]` checkbox task lists.
`deflist`	Definition lists with `Term\n: Definition` syntax.
`fieldlist`	`:Key: Value` metadata lists.
`substitution`	`{{variable}}` template replacements defined in `conf.py`.

Tip

For installation and configuration details, see MyST Parser.