Typography

MyST is a strict superset of the CommonMark syntax specification. It adds features focussed on scientific and technical documentation authoring, as detailed below.

1.  Headings

Markdown syntax denotes headers starting with between 1 to 6 #.

### Heading Level 3

Heading Level 3

Note, that headings that are not at the root level of the document will not be included in the table of contents. Using the attrs_block extension, you can also add classes to headings

> {.bg-primary}
> ### Paragraph heading

Paragraph heading

参见

To structure single and multiple documents into table of contents, see the organising content section.

To reference a heading in your text, see the cross-referencing section.

2.  Paragraphs

Paragraphs are block of text separated by a blank line.

Using the attrs_block extension, you can also add classes to paragraphs:

{.bg-primary}
Here is a paragraph with a class to control its formatting.

Here is a paragraph with a class to control its formatting.

3.  Thematic breaks

You can create a thematic break, to break content between themes, using three or more *, -, or _ characters on a line by themselves.

* * *

---

4.  Inline Text Formatting

Standard inline formatting including bold, italic, code, as well as escaped symbols and line breaks:

**strong**, _emphasis_, `literal text`, \*escaped symbols\*

strong, emphasis, literal text, *escaped symbols*

The strikethrough extension allows you to add strike-through text:

~~strikethrough with *emphasis*~~

strikethrough with emphasis

The smartquotes and replacements extensions can improve the typography of common symbols:

Smart-quotes 'single quotes' and "double quotes".

+-, --, ---, ... and other replacements.

Smart-quotes ‘single quotes’ and “double quotes”.

±, --, —, … and other replacements.

Using the attrs_inline extension, you can also add classes to inline text spans:

A paragraph with a span of [text with attributes]{.bg-warning}

A paragraph with a span of text with attributes

5.  Line Breaks

To put a line break, without a paragraph, use a \ followed by a new line. This corresponds to a <br> in HTML and \\ in LaTeX.

**Fleas** \
Adam \
Had 'em.

Fleas
Adam
Had 'em.

Added in version 3.0.

Alternatively, you can use the line-block directive, which constructs a block where all line breaks (and also initial indentations) are respected:

:::{line-block}
**Fleas**
  Adam
  Had 'em.
:::

Fleas

Adam

Had 'em.

6.  Bullet points and numbered lists

You can use bullet points and numbered lists as you would in standard Markdown. Starting a line with either a - or * for a bullet point, and 1. for numbered lists. These lists can be nested using two spaces at the start of the line.

- Lists can start with `-` or `*`
  * My other, nested
  * bullet point list!

1. My numbered list
2. has two points

• Lists can start with - or *

  • My other, nested

  • bullet point list!

1. My numbered list

2. has two points

For numbered lists, you can start following lines with any number, meaning they don’t have to be in numerical order, and this will not change the rendered output. The exception is the first number, which if it is not 1. this will change the start number of the list.

Alternate numbering styles

Using the attrs_block extension, you can also specify a alternative numbering styles:

{style=lower-alpha}
1. a
2. b

{style=upper-alpha}
1. a
2. b

{style=lower-roman}
1. a
2. b

{style=upper-roman}
1. a
2. b

1. a

2. b

1. a

2. b

1. a

2. b

1. a

2. b

Using the tasklist extension, you can also create task lists:

- [ ] An item that needs doing
- [x] An item that is complete

• An item that needs doing

• An item that is complete

7.  Subscript & Superscript

For inline typography for subscript and superscript formatting, the sub and sup role, can be used respectively.

H{sub}`2`O, and 4{sup}`th` of July

H₂O, and 4^th of July

8.  Quotations

Quotations are controlled with standard Markdown syntax, by inserting a caret (>) symbol in front of one or more lines of text.

> We know what we are, but know not what we may be.

We know what we are, but know not what we may be.

Using the attrs_block extension, you can also add an attribution attribute to a block quote:

{attribution="Hamlet act 4, Scene 5"}
> We know what we are, but know not what we may be.

We know what we are, but know not what we may be.

—Hamlet act 4, Scene 5

9.  Definition lists and glossaries

Using the definition lists extension, you can define terms in your documentation, using the syntax:

Term 1
: Definition

Term 2
: Longer definition

  With multiple paragraphs

  - And bullet points

Term 1

Definition

Term 2

Longer definition

With multiple paragraphs

• And bullet points

Using the attrs_block extension, you can also add a glossary class to a definition list, that will allow you to reference terms in your text using the term role:

{.glossary}
my term
: Definition of the term

{term}`my term`

my term

Definition of the term

my term

10.  Field lists

Using the field lists extension, you can create field lists, which are useful in source code documentation (see Sphinx docstrings):

:param arg1: A description of arg1
:param arg2: A longer description,
    with multiple lines.

    - And bullet points
:return: A description of the return value

param arg1:

A description of arg1

param arg2:

A longer description, with multiple lines.

• And bullet points

return:

A description of the return value

11.  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 won’t be parsed into the document:

% my comment

Comments split paragraphs

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
% a comment
another line

a line

another line

12.  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.

• This is a manually-numbered footnote reference.[3]

• This is an auto-numbered footnote reference.[1]

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.

By default, the footnotes will be collected, sorted and moved to the end of the document, with a transition line placed before any footnotes (that has a footnotes class).

This behaviour can be modified using the configuration options:

myst_footnote_sort = False
myst_footnote_transition = False

Added in version 4.0.0: myst_footnote_sort configuration option

---

[1]

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 preceding unindented lines, that are not separated by a blank line

[3]

This is a manually-numbered footnote definition.