MyST extensions

MyST-Parser’s optional syntax is switched on extension by extension, in the extensions list of the [parse.parsers.md] table for ubCode (see Parsers and file routing) and in myst_enable_extensions for a Sphinx build. Keep the two lists the same, so that both engines read the same syntax. This site enables the extensions below, and each example shows its source and what this site’s own build renders from it. The syntax every MyST page has without an extension is on MyST core syntax.

Colon fences (colon_fence)

A directive can be fenced with three or more colons instead of backticks, so its body can hold a backtick fence without any escaping. A fence with more colons holds one with fewer.

Colon fences

:::{note}
A note in a colon fence, with `code` in it.
:::

::::{admonition} An outer box
:::{tip}
A tip inside it.
:::
::::

Note

A note in a colon fence, with code in it.

An outer box

Tip

A tip inside it.

Definition lists (deflist)

A term is a line of its own; each line under it that starts with : is one of its definitions.

A definition list

Specimen
: A live example on a Writing page.

Twin
: The same example in the other markup.
: Rendered on a page of its own.
Specimen

A live example on a Writing page.

Twin

The same example in the other markup.

Rendered on a page of its own.

Field lists (fieldlist)

Lines of the form :name: value make a field list. At the top of a directive’s body the same lines are the directive’s options, so the list in this example follows a paragraph.

A field list

The fields of a specimen:

:Author: The docs team
:Status: Reviewed, with *markup* in the value

The fields of a specimen:

Author:

The docs team

Status:

Reviewed, with markup in the value

Task lists (tasklist)

A list item starting with [ ] or [x] is a task, drawn with an empty or a ticked box.

A task list

- [x] Write the specimen.
- [ ] Review it.

  • Write the specimen.

  • Review it.

ubc build pdf draws the items as plain bullets, without their boxes, as a Sphinx LaTeX build does. The boxes in the two HTML builds differ in one way, listed in the Markdown differences.

Alerts (alert)

A block quote whose first line is [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] is drawn as the admonition of that name, as GitHub draws it. Any other first line leaves the block quote as it is.

Alerts

> [!TIP]
> An alert is written the way GitHub reads it.

> [!WARNING]
> So the same file reads well on both sites.

Tip

An alert is written the way GitHub reads it.

Warning

So the same file reads well on both sites.

Attributes (attrs_inline, attrs_block)

A brace group gives the element before it, or the block after it, an id and classes.

Attributes

{#ex-markdown-extensions-lead}
A paragraph with an id of its own, which [a link reaches](#ex-markdown-extensions-lead),
and [a span with a class]{.ex-markdown-extensions-span}.

A paragraph with an id of its own, which a link reaches, and a span with a class.

Which keys each element takes, and how ubCode and MyST-Parser differ, is in Attributes.

Not enabled on this site

  • strikethrough (~~text~~): ubCode draws the text struck through, but MyST-Parser reports every use, even in an HTML build (Strikethrough is currently only supported in HTML output, as myst.strikethrough), so a site built with sphinx-build -W has to suppress that warning (suppress_warnings = ["myst.strikethrough"]) to use it; this site leaves it off.

  • dollarmath and amsmath ($x$, $$x$$ and bare LaTeX environments): ubCode implements both; this site writes its maths with the {math} directive and role (see Math).

  • smartquotes, replacements, html_image and attrs_image: ubCode implements them too; this site leaves them off.

  • linkify, substitution and html_admonition are not implemented by ubCode: see the unsupported extensions.