Writing content

astro-myst does not parse Markdown itself: mystmd does, so every MyST feature is available. The MyST guide is the authoritative reference; this page shows the most useful features as they render on this site, which uses astro-myst’s optional theme. Headings on this page are numbered because its frontmatter sets numbering.headings: true.

1 Frontmatter and project options#

A page starts with optional YAML frontmatter. MyST reads the keys it knows, such as title, authors, date, tags, numbering or math (see MyST’s frontmatter reference). Other keys, such as a blog’s pubDate or draft, reach the entry’s data as written; see Entry data.

---
title: Measuring decay
date: 2025-03-14
tags: [physics]
numbering:
  headings: true
draft: true
---

Settings for all pages go into the project option, where a MyST site would use the project: section of a myst.yml: on the integration for every collection, or on a loader for one collection (see Options). Page frontmatter can override or extend them for a single page.

// astro.config.ts
myst({
  project: {
    numbering: { headings: true },
    math: { '\\dd': '\\mathrm{d}' },
    abbreviations: { AST: 'abstract syntax tree' },
  },
});

2 Abstracts and other parts#

An abstract, a summary or acknowledgments can go into the frontmatter, or into the body as a block marked with +++ {"part": "abstract"}; LaTeX’s \begin{abstract} works too. MyST calls them parts:

---
title: Measuring decay
abstract: |
  We measure how the oscillations *decay*.
acknowledgments: We thank the reviewers.
---

Each part becomes a section.myst-part with a heading. Parts from the frontmatter are placed as in MyST’s themes: abstract, summary and keypoints before the content, the others after it. Their HTML is also in data.myst.parts, for example to show abstracts in a list of posts (see Frontmatter parts).

3 Labels, numbering and references#

Give anything a label and reference it with @label, [](#label) or a role such as {numref}:

(sec-numbering)=
## Labels, numbering and references

```{math}
:label: eq-wave
\frac{\partial^2 u}{\partial t^2} = c^2 \nabla^2 u
```

See @eq-wave and [](#sec-numbering).

See (1) and Section 3. References work across all pages of a collection: (1) lives on the home page, and hovering it shows a preview.

Numbering is set with numbering in the frontmatter of a page or in the project option. By default MyST restarts figure, table and equation numbers on every page; numbering.title: true gives chapter-style numbers such as 2.1, and numbering.figure.continue: true numbers figures continuously across pages:

myst({ project: { numbering: { title: true, figure: { continue: true } } } });

See MyST’s numbering docs.

4 Figures and tables#

:::{figure} ../images/pipeline.svg
:label: fig-flow
:width: 80%
The build pipeline.
:::

:::{table} Supported sources
:label: tbl-sources
| Format | Extension |
|---|---|
| MyST Markdown | `.md` |
| LaTeX | `.tex` |
| Jupyter | `.ipynb` |
:::

Figure 1 and Table 1 are numbered automatically. Figures with several images get sub-figures (Figure 2a, Figure 2b) that can be referenced individually. Image paths are relative to the page; astro-myst serves the images under /_myst/<collection>/ and copies them into the build output.

5 Math#

Inline math ($e^{i\pi} + 1 = 0$), display math with $$, the {math} directive and LaTeX environments are rendered with KaTeX at build time, so pages need no client-side JavaScript for math. Macros for all pages go into the project option (in JavaScript strings, backslashes are doubled):

myst({ project: { math: { '\\dd': '\\mathrm{d}' } } });

Macros for one page go into its frontmatter:

---
math:
  '\dd': '\mathrm{d}'
---

6 Admonitions, dropdowns and tabs#

npm install astro-myst mystmd

pnpm add astro-myst mystmd

yarn add astro-myst mystmd

Tabs with the same :sync: key switch together across the page: pick a tab above and this tab set follows. The integration’s syncTabs script does that; it is on by default (see scripts).

npm run dev

pnpm dev

yarn dev

7 Theorems and proofs#

Theorem 1 is numbered within its kind; lemmas, definitions, corollaries and the other prf: kinds work the same way.

8 Code#

import { defineCollection } from 'astro:content';
import { mystLoader } from 'astro-myst/loaders';

export const collections = { blog: defineCollection({ loader: mystLoader({ base: './src/content/blog' }) }) };

Code is highlighted with Shiki at build time; labelled listings such as Program 1 are numbered. To change the colours, see Styling. The copy button that appears when you point at the listing comes from the integration’s copyCode script, which this site turns on (myst({ scripts: { copyCode: true } }), see scripts).

9 Including files#

{include} inserts another file into a page:

```{include} _install.md
```

Start the names of files that are only included with _: the loader’s default pattern skips them, so they do not become pages of their own. For files outside the collection folder, such as a README, also list them in the loader’s extraInputs, so that astro dev recompiles when they change. This site includes its changelog that way.

10 Footnotes, abbreviations and more#

Footnotes are numbered per page.¹ Abbreviations defined in the project option get a tooltip: the AST is what astro-myst renders.

Roles for inline markup work as in MyST: _subscripts, ^superscripts, Ctrl + C, small caps, chemical formulas such as H₂O and C₆H₁₂O₆ (numbers become subscripts) and units such as 9.81 m s⁻², typeset as siunitx does.

{margin} and {aside} put a note beside the text; {sidebar} a larger box. {button} makes a link look like a button: Get started. With the optional theme it has a solid background; without it, style .myst-button yourself.

Other MyST features — {embed}, glossaries and terms, cards and grids, {iframe}, {toc} (a list of links to the page’s headings, the section’s or the project’s pages, in a nav.myst-toc) — work as well. Unknown directives from MyST plugins render as a visible placeholder until you add a custom renderer.

11 Diagrams#

{mermaid} diagrams are emitted as pre.mermaid with the diagram source. With the integration’s mermaid script (myst({ scripts: { mermaid: true } }), after npm install mermaid), Mermaid.js draws them in the browser, in dark mode too; it is loaded only on pages with a diagram:

flowchart LR
  A[MyST files] --> B[mystmd] --> C[astro-myst] --> D[Astro pages]