MyST core syntax¶
The syntax every Markdown page can use under the myst flavour,
with no extension enabled.
This page is itself written in MyST,
so each example below shows its source and, under it,
what this site’s own build renders from that very source.
The optional extensions this site enables are on MyST extensions.
Headings¶
A heading is a line starting with one to six #, one per level.
A line of text underlined with === or --- is a level 1 or level 2 heading too.
# Page title
## A section
### A subsection
Every heading on this page is one. A heading cannot be shown inside a live example: inside a directive’s body it becomes an informal heading, a rubric, rather than a section, in a Sphinx build and in ubCode alike.
Inline markup¶
Inline markup
Text can be *emphasised*, **strong**, or `code`.
A backslash keeps \*these asterisks\* as text,\
and, at the end of a line, breaks the line there.
Text can be emphasised, strong, or code.
A backslash keeps *these asterisks* as text,
and, at the end of a line, breaks the line there.
Links and targets¶
A line (name)= puts a target on the block below it.
A link whose destination starts with # reaches a target, a label or a heading;
{ref} reaches the same target by name.
Links and targets
(ex-markdown-core-target)=
This paragraph carries a target,
reached by [a Markdown link](#ex-markdown-core-target)
or {ref}`by name <ex-markdown-core-target>`.
An inline link to [MyST-Parser](https://myst-parser.readthedocs.io/),
a reference-style one to [Docutils][ex-markdown-core-docutils],
and an autolink, <https://www.sphinx-doc.org/>.
[ex-markdown-core-docutils]: https://docutils.sourceforge.io/
This paragraph carries a target, reached by a Markdown link or by name. An inline link to MyST-Parser, a reference-style one to Docutils, and an autolink, https://www.sphinx-doc.org/.
What a link destination can name, and how each is resolved, is in Cross-referencing with links.
Images¶
 places an image; the path is relative to the page,
or to the source directory when it starts with /.
An image
Note
ubc build pdf cannot place a Markdown image yet
(it reports one as build.pdf_block_unsupported),
so the PDF shows this example’s source only.
The {image} and {figure} directives are drawn:
see Images.
Lists¶
Lists
- A bullet item.
- Another, with a nested list:
1. numbered automatically,
1. and so on.
3. A numbered list can start at any number.
4. The next item follows on.
A bullet item.
Another, with a nested list:
numbered automatically,
and so on.
A numbered list can start at any number.
The next item follows on.
Block quotes¶
A block quote
> A quote is a run of lines starting with `>`.
>
> It can hold *any* markup, including a second paragraph.
A quote is a run of lines starting with
>.It can hold any markup, including a second paragraph.
Code¶
A fence of three or more backticks or tildes holds code, in the language its first line names. A block indented by four spaces is code too, with no language.
Code
```python
print("Hello from a fence")
```
~~~toml
[parse.parsers.md]
flavour = "myst"
~~~
An indented block.
print("Hello from a fence")
[parse.parsers.md]
flavour = "myst"
An indented block.
Tables¶
A pipe table takes its header from the first row, and the colons in the line under it align each column.
A pipe table
| Builder | Output | Pages |
| :--------------- | :----: | ------: |
| `ubc build html` | site | many |
| `ubc build pdf` | file | one |
Builder |
Output |
Pages |
|---|---|---|
|
site |
many |
|
file |
one |
Footnotes¶
Footnotes
A footnote is referenced [^ex-markdown-core-note] and defined anywhere on the page.
[^ex-markdown-core-note]: The definition is rendered at the foot of the page.
A footnote is referenced [1] and defined anywhere on the page.
How footnotes are numbered and collected is in Footnotes.
Roles and directives¶
A role is its name in braces followed by its content in backticks.
A directive is a fence whose first line names it in braces,
followed by its argument;
its options are :key: value lines at the top of the body,
or a YAML block between two --- lines.
Roles and directives
Press {kbd}`Ctrl+S` to save, as {abbr}`MyST (Markedly Structured Text)` spells it.
```{admonition} Options as lines
:class: tip
The body follows the options.
```
```{admonition} Options as YAML
---
class: tip
---
The same, written the other way.
```
Press Ctrl+S to save, as MyST spells it.
Options as lines
The body follows the options.
Options as YAML
The same, written the other way.
The directives and roles themselves are the same as in reStructuredText: see Directives and Roles, whose pages show each one in both markups.
Thematic breaks and front matter¶
A line of three *, - or _ draws a horizontal rule between two blocks.
It belongs between the blocks of a page, never inside a directive,
so it is shown as source only:
The text above the rule.
***
The text below it.
A YAML block between two --- lines at the very top of a file is its front matter,
which configures the whole page.
This page starts with the one below,
which gives it a keywords tag in the <head> of both HTML builds:
---
myst:
html_meta:
keywords: ubCode, MyST, Markdown
---
What the <head> tags take, and where a Sphinx build differs, is in Page <head> meta tags.
Comments¶
Comments
Only this line is.