语法插件

语法插件#

MyST-Parser 高度可配置，利用了 markdown-it-py 解析器固有的 “plugability”。以下语法是可选的（默认禁用），可以通过启用（另请参见配置）。它们的目标通常是添加更多 对 Markdown 友好 的语法；通常启用并渲染扩展了 CommonMark 规范的 markdown-it-py 插件。

要启用以下解释的所有语法：

myst_enable_extensions = [
    "amsmath",
    "attrs_inline",
    "colon_fence",
    "deflist",
    "dollarmath",
    "fieldlist",
    "html_admonition",
    "html_image",
    "linkify",
    "replacements",
    "smartquotes",
    "strikethrough",
    "substitution",
    "tasklist",
]

在 0.13.0 版本发生变更: myst_enable_extensions 替换了之前的配置选项：admonition_enable、figure_enable、dmath_enable、amsmath_enable、deflist_enable、html_img_enable

1. 排版#

将 "smartquotes" 添加到 myst_enable_extensions 中（在中），将自动将标准引号转换为其开/闭变体：

'单引号': ‘单引号’
"双引号": “双引号”

将 "replacements" 添加到 myst_enable_extensions 中（在中），将自动转换一些常见的排版文本：

text	converted
`(c)`, `(C)`	©
`(tm)`, `(TM)`	™
`(r)`, `(R)`	®
`(p)`, `(P)`	(p)
`+-`	±
`...`	…
`?....`	?..
`!....`	!..
`????????`	???
`!!!!!`	!!!
`,,,`	,
`--`	–
`---`	—

2. 删除线#

Added in version 0.17.0.

strikethrough 扩展允许在 ~~ 分隔符内的文本上添加删除线（水平线）。例如，~~删除线包含*强调*~~ 渲染为：~~删除线包含强调~~。

警告

此插件目前仅支持 HTML 输出，您需要抑制 myst.strikethrough 警告（参见构建警告）。

3. 数学快捷方式#

通过在中的 myst_enable_extensions 列表选项中添加以下一项或两项来解析数学公式：

"dollarmath" 用于解析由美元符号 $ 和 $$ 包裹的数学公式。
"amsmath" 用于直接解析 amsmath LaTeX 环境。

这些选项启用了它们各自的 Markdown 解析器插件，详见 markdown-it 插件指南。

在 0.13.0 版本发生变更: myst_dmath_enable=True 和 myst_amsmath_enable=True 已被弃用，并替换为 myst_enable_extensions = ["dollarmath", "amsmath"]

3.1. 美元符号分隔的数学公式#

启用 dollarmath 将解析以下语法：

行内数学公式： $...$
显示（块级）数学公式：$$...$$

此外，如果设置了 myst_dmath_allow_labels=True （默认值）：

带方程标签的显示（块级）数学公式： $$...$$ (1)

例如， $x_{hey}=it+is^{math}$ 渲染为 $x_{hey}=it+is^{math}$。这等同于书写：

{math}`x_{hey}=it+is^{math}`

转义美元符号

可以通过在第一个符号前添加 \ 来转义（取消）数学公式，例如 \$a$ 渲染为 $a$。转义也可以在数学公式内部使用，例如 $a=\$3$ 渲染为 $a=\$3$。

相反，\\ 将取消转义，因此 \\$a$ 渲染为 \$a$。

块级数学公式可以用 $$ 符号包裹需要解析的数学块来指定。例如：

$$
    y    & = ax^2 + bx + c \\
    f(x) & = x^2 + 2xy + y^2
$$

\[\begin{split} y & = ax^2 + bx + c \\ f(x) & = x^2 + 2xy + y^2 \end{split}\]

这等同于以下指令：

```{math}
    y    & = ax^2 + bx + c \\
    f(x) & = x^2 + 2xy + y^2
```

\[\begin{split} y & = ax^2 + bx + c \\ f(x) & = x^2 + 2xy + y^2\end{split}\]

您还可以为块级方程添加标签：

$$
e = mc^2
$$ (eqn:best)

This is the best equation {eq}`eqn:best`

(1)#\[ e = mc^2 \]

This is the best equation (1)

还有一些其他选项可用于控制美元符号数学解析：

myst_dmath_allow_space=False，将导致仅在没有初始/最终空格时解析内联数学，例如 $a$ 但不包括 $ a$ 或 $a $ 。

myst_dmath_allow_digits=False，将导致仅在没有初始/最终数字时解析内联数学，例如 $a$ 但不包括 1$a$ 或 $a$2。

如果您还希望将 $ 用作货币单位，这些选项都很有用。

Added in version 0.14.0: myst_dmath_double_inline 选项

要在内联上下文中允许显示数学（即 $$），请设置 myst_dmath_double_inline = True （默认为 False）。这允许例如：

Hence, for $\alpha \in (0, 1)$,
$$
  \mathbb P (\alpha \bar{X} \ge \mu) \le \alpha;
$$
i.e., $[\alpha \bar{X}, \infty)$ is a lower 1-sided $1-\alpha$ confidence bound for $\mu$.

Hence, for $\alpha \in (0, 1)$,

\[ \mathbb P (\alpha \bar{X} \ge \mu) \le \alpha; \]

i.e., $[\alpha \bar{X}, \infty)$ is a lower 1-sided $1-\alpha$ confidence bound for $\mu$.

3.2. 其他块元素中的数学#

数学在其他块元素（如列表或引用）中嵌套时也能正常工作：

- A list
- $$ a = 1 $$

> A block quote
> $$ a = 1 $$

A list
\[ a = 1 \]

A block quote
\[ a = 1 \]

3.3. 直接 LaTeX 数学#

通过将 "amsmath" 添加到 myst_enable_extensions （在中），您可以启用对 amsmath LaTeX 方程的直接解析。这些顶级数学环境将被直接解析：

equation, multiline, gather, align, alignat, flalign, matrix, pmatrix, bmatrix, Bmatrix, vmatrix, Vmatrix, eqnarray.

正如预期的那样，以 * 结尾的环境不会被编号，例如：

\begin{gather*}
a_1=b_1+c_1\\
a_2=b_2+c_2-d_2+e_2
\end{gather*}

\begin{align}
a_{11}& =b_{11}&
  a_{12}& =b_{12}\\
a_{21}& =b_{21}&
  a_{22}& =b_{22}+c_{22}
\end{align}

\[\begin{gather*} a_1=b_1+c_1\\ a_2=b_2+c_2-d_2+e_2 \end{gather*}\]

(2)#\[\begin{align} a_{11}& =b_{11}& a_{12}& =b_{12}\\ a_{21}& =b_{21}& a_{22}& =b_{22}+c_{22} \end{align}\]

备注

环境中的 \labels 目前无法识别，因此无法引用。希望在未来更新中实现此功能（参见 executablebooks/MyST-Parser#202）！

此语法在其他块元素（如列表或引用）中嵌套时也能正常工作：

- A list
- \begin{gather*}
  a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
  \end{gather*}

> A block quote
> \begin{gather*}
  a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
  \end{gather*}

A list
\[\begin{gather*} a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2 \end{gather*}\]

A block quote

\[\begin{gather*} a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2 \end{gather*}\]

3.4. Mathjax 与数学解析#

“当使用 sphinx.ext.mathjax 扩展（默认启用）构建 HTML 时，如果启用了 dollarmath，Myst-Parser 会将 tex2jax_ignore （MathJax v2）和 mathjax_ignore （MathJax v3）类注入到每个 MyST 文档的顶层部分，并添加以下默认 MathJax 配置：

MathJax 版本 2（参见 tex2jax 预处理器）：

MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})

MathJax 版本 3（参见文档选项）：

window.MathJax = {"options": {"processHtmlClass": "tex2jax_process|mathjax_process|math|output_area"}}

这确保 MathJax 仅处理由 dollarmath 和 amsmath 扩展标识的数学，或在 math 指令中指定的数学。

要更改此行为，请设置自定义正则表达式以识别要处理的 HTML 类，例如 myst_mathjax_classes="math|myclass"，或设置 myst_update_mathjax=False 以禁止此覆盖并处理所有 HTML 元素。

4. Linkify#

将 "linkify" 添加到 myst_enable_extensions （在中）将自动识别‘裸’网页 URL 并添加超链接：

www.example.com -> www.example.com

要仅匹配以模式开头的 URL，例如 http://example.com，请设置 myst_linkify_fuzzy_links=False。

重要

此插件要求安装 linkify-it-py。可以直接安装：pip install linkify-it-py 或通过 pip install myst-parser[linkify] 安装。

5. 替换（使用 Jinja2）#

将 "substitution" 添加到 myst_enable_extensions （在中）将允许您添加替换，可以在 conf.py 中使用 myst_substitutions 添加：

myst_substitutions = {
  "key1": "I'm a **substitution**"
}

或在文件顶部的 front-matter 部分添加（参见本节）：

---
myst:
  substitutions:
    key1: "I'm a **substitution**"
    key2: |
      ```{note}
      {{ key1 }}
      ```
    key3: |
      ```{image} img/fun-fish.png
      :alt: fishy
      :width: 200px
      ```
    key4: example
---

重要

front-matter 中的键将覆盖 conf.py 中的键。

您可以内联或作为块使用这些替换，甚至可以在其他替换中嵌套替换（但禁止循环引用）：

Inline: {{ key1 }}

Block level:

{{ key2 }}

| col1     | col2     |
| -------- | -------- |
| {{key2}} | {{key3}} |

Inline: I’m a substitution

Block level:

备注

I’m a substitution

col1

col2

备注

I’m a substitution

重要

替换仅在通常使用 Markdown 的地方进行评估，例如不在代码块中：

```
{{ key1 }}
```

{{ key1 }}

还应注意不要将不合适的指令用于内联替换。这可能导致意外结果。

替换引用作为 Jinja2 表达式进行评估，可以使用过滤器，并且在上下文中包含 Sphinx 环境（作为 env）。因此，您可以执行以下操作：

- version: {{ env.config.version }}
- docname: {{ env.docname | upper }}
- {{ "a" + "b" }}

version: 4.0.0
docname: SYNTAX/OPTIONAL
ab

如果需要，您还可以更改分隔符，例如在 conf.py 中设置：

myst_sub_delimiters = ["|", "|"]

将解析：|| "a" + "b" ||。不过应谨慎更改，以免影响其他语法。

处理替换的确切逻辑是：

将全局替换（在 conf.py 中指定）与 front-matter 替换结合，创建变量上下文（front-matter 优先）。
将 sphinx env 添加到变量上下文中。
使用 Jinja2 创建要渲染的字符串内容（传递变量上下文）。
如果替换是内联的且不是指令，则渲染时忽略块语法（如列表或块引用），否则使用所有语法规则渲染。

5.1. 替换与 URL#

替换不能直接在 URL 中使用，例如 [a link](https://{{key4}}.com) 或 <https://{{key4}}.com>。然而，由于 Jinja2 替换允许使用 Python 方法，您可以使用字符串格式化或替换：

{{ '[a link](https://{}.com)'.format(key4) }}

{{ '<https://myst-parser.readthedocs.io/en/latest/REPLACE.html>'.replace('REPLACE', env.docname) }}

a link

https://myst-parser.readthedocs.io/en/latest/syntax/optional.html

6. 使用冒号的代码栏#

通过将 "colon_fence" 添加到 myst_enable_extensions （在中），您还可以使用 ::: 分隔符来表示指令，而不是 ```。

使用冒号而不是反引号的好处是，当您在任何标准 Markdown 编辑器中工作时，内容可以正确渲染。它非常适合警告类型的指令（如指令中所述）或带标题的表格，例如：

:::{note}
This text is **standard** _Markdown_
:::

:::{table} This is a **standard** _Markdown_ title
:align: center
:widths: grid

abc | mnp | xyz
--- | --- | ---
123 | 456 | 789
:::

备注

This text is standard Markdown

This is a **standard** *Markdown* title#
abc	mnp	xyz
123	456	789

与普通指令类似，这些指令也可以嵌套：

::::{important}
:::{note}
This text is **standard** _Markdown_
:::
::::

重要

备注

This text is standard Markdown

并且可以使用参数选项：

:::{admonition} This *is* also **Markdown**
:class: warning

This text is **standard** _Markdown_
:::

This is also Markdown

This text is standard Markdown

7. Admonition 指令#

在 0.13.0 版本发生变更: myst_admonition_enable 已弃用，替换为 myst_enable_extensions = ["colon_fence"] （见上文）。此外，现在应使用 :class: myclass 选项设置类。

另请参阅 HTML 警告。

8. 自动生成的标题锚点#

MyST 解析器可以自动为标题锚点生成标签 “slugs”，以便您可以从 Markdown 链接中引用它们。例如，您可以在本地使用标题书签链接：[](#header-anchor)，或跨文件使用 [](path/to/file.md#header-anchor)。要实现这一点，请使用 myst_heading_anchors = DEPTH 配置选项，其中 DEPTH 是您希望生成链接的标题级别深度。

例如，conf.py 中的以下配置告诉 myst_parser 为 h1、h2 和 h3 级别的标题（对应于 Markdown 中的 #、## 和 ### ）生成标题锚点标签。

myst_heading_anchors = 3

然后，您可以直接插入指向文档中标题生成的锚点的 Markdown 链接：

[](#auto-generated-header-anchors)

Auto-generated header anchors

其他文件的路径应相对于当前文件：

[**link text**](./typography.md#headings)

link text

8.1. 锚点 slug 结构#

创建的锚点‘slug’旨在遵循 GitHub 实现：

小写文本
删除标点符号
用 - 替换空格
通过后缀枚举 -1 强制唯一性

要更改 slug 生成函数，请在 conf.py 中设置 myst_heading_slug_func 为接受字符串并返回字符串的函数。

Added in version 0.19.0: myst_heading_slug_func 现在也可以设置为字符串，该字符串将被解释为函数的导入路径，例如 myst_heading_slug_func = "mypackage.mymodule.slugify"。

8.2. 检查将创建的链接#

可以使用命令行工具检查将创建的链接：

$ myst-anchors -l 2 docs/syntax/optional.md
<h1 id="optional-myst-syntaxes"></h1>
<h2 id="admonition-directives"></h2>
<h2 id="auto-generated-header-anchors"></h2>
<h2 id="definition-lists"></h2>
<h2 id="images"></h2>
<h2 id="markdown-figures"></h2>
<h2 id="direct-latex-math"></h2>

9. 定义列表#

通过将 "deflist" 添加到 myst_enable_extensions（在中），您将能够使用定义列表。定义列表使用 markdown-it-py deflist 插件，该插件本身基于 Pandoc 定义列表规范。

例如，此语法可以作为嵌套项目列表的替代方案：

- Term 1
  - Definition
- Term 2
  - Definition

Term 1
- Definition
Term 2
- Definition

改为使用：

Term 1
: Definition

Term 2
: Definition

Term 1: Definition
Term 2: Definition

来自 Pandoc 文档：

每个术语必须在一行内，可以选择后跟一个空行，并且必须后跟一个或多个定义。定义以冒号或波浪号开头，可以缩进一个或两个空格。

一个术语可以有多个定义，每个定义可以包含一个或多个块元素（段落、代码块、列表等）。

这里有更复杂的示例，展示了其中一些功能：

Term *with Markdown*
: Definition [with reference](syntax/definition-lists)

  A second paragraph
: A second definition

Term 2
  ~ Definition 2a
  ~ Definition 2b

Term 3
:     A code block
: > A quote
: A final definition, that can even include images:

  <img src="img/fun-fish.png" alt="fishy" width="200px">

Term with Markdown

Definition with reference

A second paragraph

A second definition

Term 2

Definition 2a

Definition 2b

Term 3

A code block

A quote

A final definition, that can even include images:

10. 任务列表#

通过将 "tasklist" 添加到 myst_enable_extensions （在中），您将能够使用任务列表。任务列表使用 markdown-it-py tasklists 插件，并应用于以 [ ] 或 [x] 开头的 Markdown 列表项：

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

An item that needs doing
An item that is complete

11. 字段列表#

Added in version 0.16.0.

通过将 "fieldlist" 添加到 myst_enable_extensions（在中），您将能够使用字段列表。字段列表是基于 reStructureText 语法的字段名称到字段体的映射。

:name only:
:name: body
:*Nested syntax*: Both name and body may contain **nested syntax**.
:Paragraphs: Since the field marker may be quite long, the second
   and subsequent lines of a paragraph do not have to line up
   with the first line.
:Blocks:

  As well as paragraphs, any block syntaxes may be used in a field body:

  - Me
  - Myself
  - I

  ```python
  print("Hello, world!")
  ```

name only:

name:

body

Nested syntax:

Both name and body may contain nested syntax.

Paragraphs:

Since the field marker may be quite long, the second and subsequent lines of a paragraph do not have to line up with the first line.

Blocks:

As well as paragraphs, any block syntaxes may be used in a field body:

Me
Myself
I

print("Hello, world!")

字段列表的突出用例是在 API 文档字符串中使用，如 Sphinx 的文档字符串渲染器中所示：

```{py:function} send_message(sender, priority)

Send a message to a recipient

:param str sender: The person sending the message
:param priority: The priority of the message, can be a number 1-5
:type priority: int
:return: the message id
:rtype: int
:raises ValueError: if the message_body exceeds 160 characters
```

send_message(sender, priority)#

Send a message to a recipient

参数:

sender (str) -- The person sending the message
priority (int) -- The priority of the message, can be a number 1-5

返回:

the message id

返回类型:

int

抛出:

ValueError -- if the message_body exceeds 160 characters

备注

目前 sphinx.ext.autodoc 不支持 MyST，请参阅在 Markdown 文件中使用 sphinx.ext.autodoc。

12. 属性#

Added in version 0.19: 此功能处于 beta 阶段，欢迎反馈。

attrs_inline 还取代了之前的 attrs_image 插件，该插件现已弃用。

属性是一种通过向元素添加额外信息来丰富标准 CommonMark 语法的方式。

属性在大括号 {} 内指定，例如 {#my-id .my-class key="value"}，并在块元素之前或内联元素之后。

在大括号内，识别以下语法：

.foo 将 foo 指定为类。可以以这种方式指定多个类；它们将被合并。
#foo 将 foo 指定为标识符。一个元素只能有一个标识符；如果指定了多个标识符，则使用最后一个。
key="value" 或 key=value 指定键值属性。当值完全由 ASCII 字母数字字符或 _ 或 : 或 - 组成时，不需要引号。引号内的值可以使用反斜杠转义。注意仅支持某些键，见下文。
% 开始注释，注释以下一个 % 或属性结束（}）。

属性是累积的，因此如果多个属性彼此跟随，内部属性会覆盖外部属性。例外是，如果指定了多个类，它们将被合并。例如：

{#id1 .class1 key1="value1"}
{#id2 .class2 key2="value2"}
block

[inline]{#id2 .class2 key2="value2"}{#id1 .class1 key1="value1"}

等价于：

{#id2 .class1 .class2 key1="value1" key2="value2"}
block

[inline]{#id2 .class1 .class2 key1="value1" key2="value2"}

参见

这是改编自 djot 内联/块属性，并且与 pandoc 括号跨度相关。

12.1. 块属性#

通过将 "attrs_block" 添加到 myst_enable_extensions（在中），您可以在某些块语法之前启用块属性的解析。

例如，以下 Markdown：

{#mypara .bg-warning}
Here is a paragraph with attributes.

{ref}`A reference to my paragraph <mypara>`

Here is a paragraph with attributes.

A reference to my paragraph

大多数块语法支持 id 和 class，但每种语法仅支持某些键值属性。

对于 有序列表，支持 style 键，可以是 decimal、lower-alpha、upper-alpha、lower-roman、upper-roman 之一：

{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

a
b

a
b

a
b

a
b

对于 代码栏，支持 lineno-start 和 emphasize-lines 键：

{lineno-start=1 emphasize-lines="2,3"}
```python
a = 1
b = 2
c = 3
```

a = 1
b = 2
c = 3

对于 块引用，支持 attribution 键：

{attribution="Chris Sewell, [link](https://example.com)"}
> Hallo

Hallo

—Chris Sewell, link

对于 定义列表，添加 glossary 键将定义列表转换为术语表（类似于在 Sphinx 中使用 glossary 指令）：

{.glossary}
term name
: Definition of the term

{term}`term name`

term name: Definition of the term

term name

12.2. 内联属性#

通过将 "attrs_inline" 添加到 myst_enable_extensions （在中），您可以在某些内联语法之后启用内联属性的解析。

例如，以下 Markdown：

- [A span of text with attributes]{#spanid .bg-warning},
  {ref}`a reference to the span <spanid>`

- `A literal with attributes`{#literalid .bg-warning},
  {ref}`a reference to the literal <literalid>

- An autolink with attributes: <https://example.com>{.bg-warning title="a title"}

- [A link with attributes](syntax/attributes){#linkid .bg-warning},
  {ref}`a reference to the link <linkid>`

- ![An image with attribute](img/fun-fish.png){#imgid .bg-warning w=100px align=center}
  {ref}`a reference to the image <imgid>`

A span of text with attributes, a reference to the span
A literal with attributes, {ref}`a reference to the literal
An autolink with attributes: https://example.com
A link with attributes, a reference to the link
a reference to the image

大多数内联语法支持 id 和 class，但每种语法仅支持某些键值属性。

对于 字面量，支持以下属性：

language/lexer/l 定义语法词法分析器，例如 `a = "b"`{l=python} 显示为 a = "b"。注意，这仅在 sphinx >= 5 中支持。

对于图像，支持以下属性（等同于 image 指令）：

width/w 定义图像的宽度（以 %、px、em、cm 等为单位）
height/h 定义图像的高度（以 px、em、cm 等为单位）
align/a 定义图像的对齐方式（left、center 或 right）

13. HTML 图片#

MyST 提供了几种不同的语法来在文档中包含图像，如下所述。

首先是标准的 Markdown 语法：

![fishy](img/fun-fish.png)

fishy

此语法将正确地将图像复制到构建文件夹，并将其在所有输出格式（HTML、TeX 等）中呈现。但它在可应用的配置方面受到限制，例如设置宽度。

如上文所述，MyST 允许使用 image 和 figure 等指令（参见 Sphinx 文档）：

```{image} img/fun-fish.png
:alt: fishy
:class: bg-primary
:width: 200px
:align: center
```

然而，现在可以设置其他选项，但与 Markdown 语法相比，此语法不会在常见的 Markdown 查看器中显示图像（例如在 GitHub 上查看文件时）。

最后一种选择是直接使用 HTML，MyST 也会解析它。这通常是不好的选择，因为在构建过程中 HTML 被视为原始文本，因此 sphinx 不会识别要复制的图像文件，并且不会将 HTML 输出到非 HTML 输出格式中。

HTML 解析来拯救！

通过将 "html_image" 添加到 myst_enable_extensions （在中），MySt-Parser 将尝试将任何孤立的 img 标签（即未包裹在任何其他 HTML 中）转换为 sphinx 中使用的内部表示。

<img src="img/fun-fish.png" alt="fishy" width="200px">
<img src="img/fun-fish.png" alt="fishy" width="200px" class="bg-primary">

允许的属性等同于 image 指令：src、alt、class、width、height 和 name。任何其他属性将被丢弃。

HTML 图像也可以内联使用！

I’m an inline image:

14. Markdown 图表#

通过将 "colon_fence" 添加到 myst_enable_extensions（在中），可以结合上述两种扩展语法，创建一个完全符合 Markdown 的 figure 指令版本，名为 figure-md。

在 0.13.0 版本发生变更: myst_figure_enable 与 figure 指令已弃用，替换为 myst_enable_extensions = ["colon_fence"] 和 figure-md。

图表块必须仅包含两个部分；一个图像，可以是 Markdown 或 HTML 语法，以及一个用于标题的段落。

第一行参数是可选的，并作为图表的引用目标：

:::{figure-md}
![fishy](img/fun-fish.png){.bg-primary .mb-1 width=200px}

This is a caption in **Markdown**
:::

:::{figure-md} fig-target
:class: myclass

<img src="img/fun-fish.png" alt="fishy" class="bg-primary mb-1" width="200px">

This is a caption in **Markdown**
:::

正如在这里看到的，设置的目标可以被引用：

[Go to the fish!](#fig-target)

Go to the fish!

15. HTML 警告#

通过将 "html_admonition" 添加到 myst_enable_extensions（在中），您可以启用 <div class="admonition"> HTML 块的解析。这些块将在内部转换为 Sphinx 警告指令，因此适用于所有输出格式。当您关心查看‘源’Markdown 时，这很有帮助，例如在 Jupyter Notebooks 中。

如果 div 内的第一个元素是 <div class="title"> 或 <p class="title">，则将其设置为警告标题。所有内部文本（和标题）将作为 MyST-Markdown 解析，所有类和可选名称将传递给警告：

<div class="admonition note" name="html-admonition" style="background: lightgreen; padding: 10px">
<p class="title">This is the **title**</p>
This is the *content*
</div>

This is the title

This is the content

在 Sphinx 渲染期间，class 和 name 属性将被 Sphinx 使用，但任何其他属性（如 style）将被丢弃。

警告

块中不能有空行，否则它们将被读取为两个单独的块。如果要使用多个段落，可以将它们包裹在 <p> 中：

<div class="admonition note">
<p>Paragraph 1</p>
<p>Paragraph 2</p>
</div>

Note

Paragraph 1

Paragraph 2

您还可以嵌套 HTML 警告：

<div class="admonition">
<p>Some **content**</p>
  <div class="admonition tip">
  <div class="title">A *title*</div>
  <p>Paragraph 1</p>
  <p>Paragraph 2</p>
  </div>
</div>

Note

Some content

A title

Paragraph 1

Paragraph 2

语法插件

目录

语法插件#

1. 排版#

2. 删除线#

3. 数学快捷方式#

3.1. 美元符号分隔的数学公式#

3.2. 其他块元素中的数学#

3.3. 直接 LaTeX 数学#

3.4. Mathjax 与数学解析#

4. Linkify#

5. 替换（使用 Jinja2）#

5.1. 替换与 URL#

6. 使用冒号的代码栏#

7. Admonition 指令#

8. 自动生成的标题锚点#

8.1. 锚点 slug 结构#

8.2. 检查将创建的链接#

9. 定义列表#

10. 任务列表#

11. 字段列表#

12. 属性#

12.1. 块属性#

12.2. 内联属性#

13. HTML 图片#

14. Markdown 图表#

15. HTML 警告#