Core Syntax
Contents
Core Syntax#
Introduction#
MyST is a strict superset of the CommonMark syntax specification. It adds features focussed on scientific and technical documentation authoring, as detailed below.
In addition, the roles and directives syntax provide inline/block-level extension points for plugins. This is detailed further in the Roles and Directives section.
See also
CommonMark#
The CommonMark syntax specification details the full set of syntax rules. Here we provide a summary of most features:
Element |
Syntax |
---|---|
Heading |
|
Bold |
|
Italic |
|
Inline Code |
|
Autolink |
|
URL Link |
|
Image |
|
Reference Link |
|
Link Definition |
|
Thematic break |
|
Blockquote |
|
Ordered List |
|
Unordered List |
|
Code Fence |
opening |
Front Matter#
This is a YAML block at the start of the document, as used for example in jekyll.
The document should start with three or more ---
markers, and YAML is parsed until a closing ---
marker is found:
---
key1: value
key2: [value1, value2]
key3:
subkey1: value
---
See also
Top-matter is also used for the substitution syntax extension, and can be used to store information for blog posting (see ablog’s myst-parser support).
Setting a title#
New in version 0.17.0.
If myst_title_to_header
is set to True
, and a title
key is present in the front matter,
then the title will be used as the document’s header (parsed as Markdown).
For example:
---
title: My Title with *emphasis*
---
would be equivalent to:
# My Title with *emphasis*
Setting HTML Metadata#
The front-matter can contain the special key html_meta
; a dict with data to add to the generated HTML as <meta>
elements.
This is equivalent to using the RST meta
directive.
HTML metadata can also be added globally in the conf.py
via the myst_html_meta
variable, in which case it will be added to all MyST documents.
For each document, the myst_html_meta
dict will be updated by the document level front-matter html_meta
, with the front-matter taking precedence.
language = "en"
myst_html_meta = {
"description lang=en": "metadata description",
"description lang=fr": "description des métadonnées",
"keywords": "Sphinx, MyST",
"property=og:locale": "en_US"
}
---
myst:
html_meta:
"description lang=en": "metadata description"
"description lang=fr": "description des métadonnées"
"keywords": "Sphinx, MyST"
"property=og:locale": "en_US"
---
.. meta::
:description lang=en: metadata description
:description lang=fr: description des métadonnées
:keywords: Sphinx, MyST
:property=og:locale: en_US
<html lang="en">
<head>
<meta content="metadata description" lang="en" name="description" xml:lang="en" />
<meta content="description des métadonnées" lang="fr" name="description" xml:lang="fr" />
<meta name="keywords" content="Sphinx, MyST">
<meta content="en_US" property="og:locale" />
Block Breaks#
You may add a block break by putting +++
at the beginning of a line.
This constuct’s intended use case is for mapping to cell based document formats,
like jupyter notebooks,
to indicate a new text cell. It will not show up in the rendered text,
but is stored in the internal document structure for use by developers.
For example, this code:
+++ some text
Is below, but it won’t be parsed into the document.
Markdown Links and Referencing#
Markdown links are of the form: [text](link)
.
If you set the configuration myst_all_links_external = True
(False
by default),
then all links will be treated simply as “external” links.
For example, in HTML outputs, [text](link)
will be rendered as <a href="link">text</a>
.
Otherwise, links will only be treated as “external” links if they are prefixed with a scheme,
configured with myst_url_schemes
(by default, http
, https
, ftp
, or mailto
).
For example, [example.com](https://example.com)
becomes example.com.
Note
The text
will be parsed as nested Markdown, for example [here's some *emphasised text*](https://example.com)
will be parsed as here’s some emphasised text.
For “internal” links, myst-parser in Sphinx will attempt to resolve the reference to either a relative document path, or a cross-reference to a target (see Targets and Cross-Referencing):
[this doc](syntax.md)
will link to a rendered source document: this docThis is similar to
{doc}`this doc <syntax>`
; this doc, but allows for document extensions, and parses nested Markdown text.
[example text](example.txt)
will link to a non-source (downloadable) file: example textThe linked document itself will be copied to the build directory.
This is similar to
{download}`example text <example.txt>`
;example text
, but parses nested Markdown text.
[reference](syntax/referencing)
will link to an internal cross-reference: referenceThis is similar to
{any}`reference <syntax/referencing>`
; reference, but parses nested Markdown text.You can limit the scope of the cross-reference to specific sphinx domains, by using the
myst_ref_domains
configuration. For example,myst_ref_domains = ("std", "py")
will only allow cross-references tostd
andpy
domains.
Additionally, only if Auto-generated header anchors are enabled, then internal links to document headers can be used.
For example [a header](syntax.md#markdown-links-and-referencing)
will link to a header anchor: a header.
Targets and Cross-Referencing#
Targets are used to define custom anchors that you can refer to elsewhere in your documentation. They generally go before section titles so that you can easily refer to them.
Tip
If you’d like to automatically generate targets for each of your section headers, check out the Auto-generated header anchors section of extended syntaxes.
Target headers are defined with this syntax:
(header_target)=
They can then be referred to with the ref inline role:
{ref}`header_target`
By default, the reference will use the text of the target (such as the section title), but also you can directly specify the text:
{ref}`my text <header_target>`
For example, see this ref: Targets and Cross-Referencing, and here’s a ref back to the top of this page: my text.
Alternatively using the markdown syntax:
[my text](header_target)
is equivalent to using the any inline role:
{any}`my text <header_target>`
but can also accept “nested” syntax (like bold text) and will recognise document paths that include extensions (e.g. syntax/syntax
or syntax/syntax.md
)
Using the same example, see this ref: Targets and Cross-Referencing, here is a reference back to the top of
this page: my text with nested \(\alpha\) syntax, and here is a reference to another page ([](../intro.md)
): Get Started.
Note
If you wish to have the target’s title inserted into your text, you can
leave the “text” section of the markdown link empty. For example, this
markdown: [](syntax.md)
will result in: Core Syntax.
Code syntax highlighting#
Code blocks contain a language identifier, which is used to determine the language of the code. This language is used to determine the syntax highlighting, using an available pygments lexer.
```python
from a import b
c = "string"
```
from a import b
c = "string"
You can create and register your own lexer, using the pygments.lexers
entry point,
or within a sphinx extension, with the app.add_lexer
method.
Using the myst_number_code_blocks
configuration option, you can also control whether code blocks are numbered by line.
For example, using myst_number_code_blocks = ["typescript"]
:
1type MyBool = true | false;
2
3interface User {
4 name: string;
5 id: number;
6}
Show backticks inside raw markdown blocks#
If you’d like to show backticks inside of your markdown, you can do so by nesting them in backticks of a greater length. Markdown will treat the outer-most backticks as the edges of the “raw” block and everything inside will show up. For example:
`` `hi` ``
will be rendered as: `hi`
and
````
```
hi
```
````
will be rendered as:
```
hi
```
Tables#
Tables can be written using the standard Github Flavoured Markdown syntax:
| foo | bar |
| --- | --- |
| baz | bim |
foo |
bar |
---|---|
baz |
bim |
Cells in a column can be aligned using the :
character:
| left | center | right |
| :--- | :----: | ----: |
| a | b | c |
left |
center |
right |
---|---|---|
a |
b |
c |
Note
Text is aligned by assigning text-left
, text-center
, or text-right
to the cell.
It is then necessary for the theme you are using to include the appropriate css styling.
<table class="colwidths-auto table">
<thead>
<tr><th class="text-left head"><p>left</p></th></tr>
</thead>
<tbody>
<tr><td class="text-left"><p>a</p></td></tr>
</tbody>
</table>
Images#
MyST provides a few different syntaxes for including images in your documentation.
The standard Markdown syntax is:
![fishy](img/fun-fish.png)
But you can also enable extended image syntaxes, to control attributes like width and captions. See the extended image syntax guide.
Footnotes#
Footnotes use the pandoc specification.
Their labels start with ^
and can then be any alphanumeric string (no spaces), which is case-insensitive.
If the label is an integer, then it will always use that integer for the rendered label (i.e. they are manually numbered).
For any other labels, they will be auto-numbered in the order which they are referenced, skipping any manually numbered labels.
All footnote definitions are collected, and displayed at the bottom of the page (in the order they are referenced). Note that un-referenced footnote definitions will not be displayed.
- This is a manually-numbered footnote reference.[^3]
- This is an auto-numbered footnote reference.[^myref]
[^myref]: This is an auto-numbered footnote definition.
[^3]: This is a manually-numbered footnote definition.
Any preceding text after a footnote definitions, which is indented by four or more spaces, will also be included in the footnote definition, and the text is rendered as MyST Markdown, e.g.
A longer footnote definition.[^mylongdef]
[^mylongdef]: This is the _**footnote definition**_.
That continues for all indented lines
- even other block elements
Plus any preceding unindented lines,
that are not separated by a blank line
This is not part of the footnote.
A longer footnote definition.2
This is not part of the footnote.
Important
Although footnote references can be used just fine within directives, e.g.1, it is recommended that footnote definitions are not set within directives, unless they will only be referenced within that same directive:
[^other]
[^other]: A definition within a directive
This is because, in the current implementation, they may not be available to reference in text above that particular directive.
By default, a transition line (with a footnotes
class) will be placed before any footnotes.
This can be turned off by adding myst_footnote_transition = False
to the config file.
- 3
This is a manually-numbered footnote definition.
- 1(1,2)
This is an auto-numbered footnote definition.
- 2
This is the footnote definition.
That continues for all indented lines
even other block elements
Plus any subsequent unindented lines, that are not separated by a blank line
- 4
A definition within a directive
Comments#
You may add comments by putting the
%
character at the beginning of a line. This will prevent the line from being parsed into the output document.For example, this code:
Is below, but it won’t be parsed into the document.
Important
Since comments are a block-level entity, they will terminate the previous block. In practical terms, this means that the following lines will be broken up into two paragraphs, resulting in a new line between them:
a line
another line
Tip
Comments are equivalent to the RST syntax:
.. my comment
.