跳转至主要内容
`Ctrl`+`K`

# Typography

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

## Headings

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

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

参见

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.

## Paragraphs

Paragraphs are block of text separated by a blank line.

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

## Thematic breaks

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

## Inline Text Formatting

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

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

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

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

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

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:

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

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:

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

## Subscript & Superscript

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

## Quotations

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

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

## Definition lists and glossaries

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

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:

## Field lists

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

## 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:

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:

## 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.[1]

[1]

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.

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