Markdown (MyST)

ubCode can parse and preview Markdown as well as reStructuredText. Enabling Markdown for a project, and choosing its flavour (commonmark, gfm, or myst), happens in your project configuration through the [parse.parsers.md] table — see Parsers and file routing for the keys, file routing, and extension options.

The myst flavour is the full authoring surface. Markdown is rendered through the same preview engine as reStructuredText, so under myst the same directives and roles you already use in reStructuredText render identically in Markdown — you write them with MyST syntax rather than reStructuredText syntax.

This reference describes the Rendered preview mode; in Structural mode every directive and role renders as a uniform placeholder, identically for reStructuredText and MyST (see Authoring). For the handful of preview behaviours that apply to reStructuredText but not Markdown, see Differences from a Sphinx build.

Flavours

The flavour selects a base set of enabled syntax. Only myst understands directives and roles; choose it for Sphinx-Needs-style content in Markdown.

Flavour	What it enables
myst	CommonMark, GFM tables, and the full MyST surface: directives, roles, targets, front matter, and footnotes. Optional extensions (definition lists, dollar math, colon fences, …) are enabled individually.
gfm	GitHub Flavored Markdown: tables, strikethrough, task lists, autolinks, and GitHub-style alerts. No directives or roles.
commonmark	Plain CommonMark (the default). No tables, directives, roles, front matter, or footnotes.

What renders

Under the myst flavour the preview renders the following constructs. Several of them — task lists, GitHub-style alerts, definition and field lists, and math — are optional extensions: the gfm flavour turns task lists and alerts on by default, while under myst you enable the ones you need (see Parsers and file routing).

Construct	Syntax
Headings	# through ###### (and setext underlines); headings nest into sections.
Lists and task lists	- / * / 1.; task items - [x] and - [ ].
Tables	GFM pipe tables with per-column alignment.
Code blocks	Fenced (backtick or ~~~ fences) or indented; language taken from the fence info string.
Block quotes	> prefixed lines.
Alerts	> [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION] render as admonitions carrying the GitHub-style label.
Footnotes	reference markers [^label] and their [^label]: definitions.
Front matter	a leading --- … --- block.
Definition and field lists	a term line with : definition blocks; :name: value field lists.
Math	$…$ inline and $$…$$ block; shown as raw source, not typeset.
Thematic breaks	***, ---, or ___.
Links and images	[text](url), autolinks <https://…>, and  images.

Directives in MyST

A MyST directive is a fenced block whose info string is a name in braces. Three fence forms are recognised — a backtick fence, a tilde fence, or (only when the colon_fence extension is enabled) a colon fence:

```{name}
body
```

~~~{name}
body
~~~

:::{name}
body
:::

The argument is the text after {name} on the opening line; options are given either as :key: value lines or as a leading --- … --- YAML block; the remaining lines are the body.

Because Markdown renders through the same engine as reStructuredText, the same directive set is available and renders to the same rich shapes: admonitions, image and figure, diagram directives, need cards, if, version-change markers, and structural blocks. For what each family renders (and which fall back to a placeholder), see Directives; for need directives and their cards see Needs; for Mermaid and PlantUML see Diagrams.

A colon-fence admonition:

:::{note}
Colon fences avoid escaping backticks when the body contains fenced code.
:::

A need card, written with a backtick fence:

```{req} Login must be secure
:id: REQ_001
:status: open

The login form must be served over TLS.
```

Roles in MyST

An inline role is written {name}`text` — the role name in braces, immediately followed by the target text in backticks. The same roles available in reStructuredText are available in Markdown; see Roles for the full set and how each renders.

Cross-reference roles such as {ref} and {need} hydrate exactly as they do in reStructuredText: until the project has been indexed in the background they show as placeholder chips, and once indexing completes they become clickable links to their targets.

See {ref}`config_parsers` and the need {need}`REQ_001`.

Note that MyST has no bare-backtick role: single backticks are always inline code, never interpreted text (see Differences from a Sphinx build).

Differences from the reStructuredText preview

A few reStructuredText preview behaviours do not carry over to Markdown:

• File splicing. The .. include:: mechanism does not apply to Markdown; a MyST {include} renders as a placeholder rather than splicing in the target file.

• Prolog and epilog. rst_prolog and rst_epilog are applied to reStructuredText documents only; they add nothing to a Markdown preview.

• No default role. Because single backticks are always inline code in MyST, there is no bare-interpreted-text default role, and the default_role setting has no effect on Markdown.

See Differences from a Sphinx build for the complete register of preview-versus-build differences.

See also

• Parsers and file routing — enabling Markdown, flavours, and extensions.

• Directives — the directive set shared with reStructuredText.

• Roles — the role set shared with reStructuredText.

• Differences from a Sphinx build — where the preview differs from a Sphinx build.