Syntax tokens

Syntax tokens#

This page serves as a reference for the syntax that makes of MyST Markdown.

参见

For more description and explanation of MyST syntax, see the syntax guide.

1.  Block (Multi-line) Tokens#

Block tokens span multiple lines of content. They are broken down into two sections:

备注

Because MyST markdown was inspired by functionality that exists in reStructuredText, we have shown equivalent rST syntax for many MyST markdown features below.

1.1.  Extended block tokens#

Token

Description

Example

FrontMatter

A YAML block at the start of the document enclosed by ---

 
---
key: value
---

Directives

enclosed in 3 or more backticks followed by the directive name wrapped in curly brackets {}. See Directives - a block-level extension point for more details.

 
```{directive}
:option: value

content
```

Math

$$ (default) or \[…\] characters wrapping multi-line math, or even direct amsmath LaTeX equations (optional). See Math shortcuts for more information.

 
$$
a=1
$$

Table

Standard markdown table style, with pipe separation.

 
| a    | b    |
| :--- | ---: |
| c    | d    |

LineComment

A commented line. See Comments for more information.

 
% this is a comment

BlockBreak

Define blocks of text. See Thematic breaks for more information.

 
+++ {"meta": "data"}

Footnote

A definition for a referencing footnote, that is placed at the bottom of the document. See Footnotes for more details.

 
[^ref]: Some footnote text

Admonitions (optional)

An alternative approach for admonition style directives only, which has the benefit of allowing the content to be rendered in standard markdown editors. See admonition directives for more details.

 
:::{note}
*content*
:::

1.2.  CommonMark tokens#

Token

Description

Example

HTMLBlock

Any valid HTML (rendered in HTML output only)

 
<p>some text</p>

BlockCode

indented text (4 spaces or a tab)

 
    included as literal *text*

Heading

Level 1-6 headings, denoted by number of #

 
### Heading level 3

SetextHeading

Underlined header (using multiple = or -)

 
Header
======

Quote

Quoted text

 
> this is a quote

CodeFence

Enclosed in 3 or more ` or ~ with an optional language name. See Source code and APIs for more information.

 
```python
print('this is python')
```

ThematicBreak

Creates a horizontal line in the output

 
---

List

bullet points or enumerated.

 
- item
  - nested item
1. numbered item

LinkDefinition

A substitution for an inline link, which can have a reference target (no spaces), and an optional title (in ")

 
[key]: https://www.google.com "a title"

Paragraph

General inline text

 
any *text*

2.  Span (Inline) Tokens#

Span (or inline) tokens are defined on a single line of content. They are broken down into two sections below:

2.1.  Extended inline tokens#

Token

Description

Example

Role

See Roles - an in-line extension point for more information.

 
{rolename}`interpreted text`

Target

Precedes element to target, e.g. header. See Creating explicit targets for more information.

 
(target)=

Math

$ (default) or \(…\) enclosed math. See Math shortcuts for more information.

 
$a=1$ or $$a=1$$

FootReference

Reference a footnote. See Footnotes for more details.

 
[^abc]

2.2.  CommonMark inline tokens#

Token

Description

Example

HTMLSpan

Any valid HTML (rendered in HTML output only)

 
<p>some text</p>

EscapeSequence

Escaped symbols (to avoid them being interpreted as other syntax elements)

 
\*

AutoLink

Link that is shown in final output

 
<http://www.google.com>

InlineCode

Literal text

 
`a=1`

LineBreak

Soft or hard (ends with spaces or backslash)

 
A hard break\

Image

Link to an image. You can also use HTML syntax, to include image size etc, see here for details

 
![alt](src "title")

Link

Reference LinkDefinitions. See Cross-references for more details.

 
[text](target "title") or [text][key]

Strong

Bold text

 
**strong**

Emphasis

Italic text

 
*emphasis*

RawText

Any text

 
any text