排版

MyST 是 CommonMark 语法规范 的严格超集。它增加了专注于科学和技术文档编写的功能，具体如下所述。

1.  标题

Markdown 语法使用 1 到 6 个 # 来表示标题。

### Heading Level 3

Heading Level 3

请注意，不在文档根级别的标题将不会包含在目录中。使用 attrs_block 插件，你还可以为标题添加类。

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

Paragraph heading

参见

要将单个或多个文档组织成目录，请参阅 组织内容部分。

要在文本中引用标题，请参阅 交叉引用部分。

2.  段落

段落是由空白行分隔的文本块。

使用 attrs_block 插件，你也可以为段落添加类。

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

这是带有类的段落，用于控制其格式。

3.  主题分隔线

你可以使用三个或更多的 *、- 或 _ 字符单独成行，来创建主题分隔线，以分隔不同主题的内容。

* * *

---

4.  内联文本格式化

标准的内联格式化包括加粗、斜体、代码，以及转义符号和换行符：

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

加粗、斜体、代码文本、*转义符号*

删除线 插件允许你添加删除线文本：

~~strikethrough with *emphasis*~~

删除线带斜体

智能引号 和 替换 插件可以改善常见符号的排版：

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

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

智能引号 ‘单引号’ 和 “双引号”。

±, --, —, … 以及其他替换。

使用 attrs_inline 插件，你还可以为内联文本添加类：

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

一段带有具有属性的文本的段落

5.  换行

若要插入换行而非新段落，请使用 \ 并紧跟新行。这相当于 HTML 中的 <br> 和 LaTeX 中的 \\。

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

Fleas
Adam
Had 'em.

Added in version 3.0.

或者，您可以使用 line-block 指令，它构建了一个块，其中所有的换行（以及初始缩进）都将被保留：

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

Fleas

Adam

Had 'em.

6.  项目符号和编号列表

您可以像在标准 Markdown 中一样使用项目符号和编号列表。以 - 或 * 开头的行表示项目符号，以 1. 开头的行表示编号列表。

- 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

对于编号列表，你可以从任何数字开始后续的行，这意味着它们不必按数字顺序排列，这不会影响渲染后的输出。唯一的例外是第一个数字，如果它不是1.，这将改变列表的起始编号。

交替编号样式

使用 attrs_block 扩展，您还可以指定交替的编号样式：

{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

使用 tasklist 插件，您还可以创建任务列表：

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

• An item that needs doing

• An item that is complete

7.  下标和上标

对于下标和上标的行内排版格式，可以分别使用 sub 和 sup role。

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

H₂O, and 4^th of July

8.  引用

引用通过标准的 Markdown 语法控制，只需在一行或多行文本前插入尖括号 (>) 符号即可。

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

知道自己是什么，却不知道自己可能成为什么。

使用 attrs_block 插件，您还可以为引用块添加 attribution 属性：

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

知道自己是什么，却不知道自己可能成为什么。

—Hamlet act 4, Scene 5

9.  定义列表与术语表

使用 definition列表 插件，您可以通过以下语法在文档中定义术语：

Term 1
: Definition

Term 2
: Longer definition

  With multiple paragraphs

  - And bullet points

Term 1

定义

Term 2

Longer definition

With multiple paragraphs

• And bullet points

使用 attrs_block 插件，您还可以为定义列表添加 glossary 类，这将允许您使用 term 角色 在文本中引用术语：

{.glossary}
my term
: Definition of the term

{term}`my term`

my term

Definition of the term

my term

10.  字段列表

使用 字段列表 插件，您可以创建字段列表，这在源代码文档中非常有用（参见 Sphinx 文档字符串）：

: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.  注释

您可以通过在行首添加 % 字符来添加注释。这将防止该行被解析到输出文档中。

例如，以下内容不会被解析到文档中：

% my comment

注释会分隔段落

由于注释是块级元素，它们会终止前一个块。实际上，这意味着以下行将被分成两个段落，从而在它们之间产生新行：

a line
% a comment
another line

a line

another line

12.  脚注

脚注遵循 pandoc 规范。它们的标签以 ^ 开头，随后可以是任何字母数字字符串（不能包含空格），且不区分大小写。

• 如果标签是整数，则渲染时将始终使用该整数作为标签（即手动编号）。

• 对于其他任何标签，它们将按照被引用的顺序自动编号，并跳过任何手动编号的标签。

所有脚注定义会被收集起来，并按引用顺序显示在页面底部。请注意，未引用的脚注定义将不会显示。

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

• 这是手动编号的脚注引用。[3]

• 这是自动编号的脚注引用。[1]

在脚注定义之后，任何缩进四个或更多空格的前置文本也将包含在脚注定义中，并且该文本会以 MyST Markdown 格式渲染，例如：

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.

较长的脚注定义。[2]

这不是脚注的一部分。

默认情况下，脚注会被收集、排序并移动到文档末尾，并在任何具有 footnotes 类的脚注之前放置转换行。

此行为可以通过 配置选项 进行修改：

myst_footnote_sort = False
myst_footnote_transition = False

Added in version 4.0.0: myst_footnote_sort 配置选项

---

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