角色与指令

角色与指令#

角色和指令通过根据名称将一段文本解释为特定类型的标记，提供了一种无限制地扩展 MyST 语法的方式。

大多数 docutils 角色、docutils 指令、Sphinx 角色 或 Sphinx 指令 都可以在 MyST 中使用。

1.  语法#

1.1.  指令 - 块级扩展点#

指令语法由三重反引号和花括号定义。它实际上是带有花括号的 Markdown 代码围栏，其中包含指令名称而不是语言名称。以下是基本结构：

MyST

reStructuredText

 
```{directivename} arguments
:key1: val1
:key2: val2

This is
directive content
```

.. directivename:: arguments
   :key1: val1
   :key2: val2

   This is
   directive content

例子：

```{admonition} This is my admonition
This is my note
```

This is my admonition

This is my note

参数化指令（选项）#

许多指令可以在指令开头的可选 选项块 中接受键/值对。

选项块从指令主体的第一行开始，由一组以 : 为前缀的行定义。

该块遵循类似 YAML 的映射语法，其中键（字符串）和值（字符串）由冒号（:）分隔：

```{code-block} python
:lineno-start: 10
:emphasize-lines: 1, 3

a = 2
print('my 1st line')
print(f'my {a}nd line')
```

10a = 2
11print('my 1st line')
12print(f'my {a}nd line')

值可以用引号（" 或 '）括起来，并跨越多行。换行行为可以通过以 | （保留换行符）或 > （折叠换行符）开始值来控制：

```{code-block} python
:lineno-start: 10
:emphasize-lines: "1, 3"
:caption: |
:     This is my
:     multi-line caption. It is *pretty nifty* ;-)

a = 2
print('my 1st line')
print(f'my {a}nd line')
```
This is my multi-line caption. It is pretty nifty ;-)#
10a = 2
11print('my 1st line')
12print(f'my {a}nd line')
旧式选项块

选项块也可以用 --- 括起来，无需 : 前缀，例如：

```{code-block} python
---
lineno-start: 10
emphasize-lines: 1, 3
caption: |
    This is my
    multi-line caption. It is *pretty nifty* ;-)
---
a = 2
print('my 1st line')
print(f'my {a}nd line')
```
This is my multi-line caption. It is pretty nifty ;-)#
10a = 2
11print('my 1st line')
12print(f'my {a}nd line')

指令如何解析内容#

一些指令会解析其内容块中的内容。MyST 将这些内容 作为Markdown 进行解析。

这意味着可以在任何以 MyST markdown 编写的指令的内容区域中编写 MyST markdown。例如：

```{admonition} My markdown link
Here is [markdown link syntax](https://jupyter.org)
```

My markdown link

Here is markdown link syntax

对于不需要参数的指令，并且当没有使用参数选项时（见下文），您可以直接在指令名称后开始内容。

```{note} Notes require **no** arguments, so content can start here.
```

备注

Notes require no arguments, so content can start here.

对于特殊情况，MySt 还提供了 eval-rst 指令。这将把内容 作为 ReStructuredText 进行解析：

```{eval-rst}
.. figure:: img/fun-fish.png
  :width: 100px
  :name: rst-fun-fish

  Party time!

A reference from inside: :ref:`rst-fun-fish`

A reference from outside: :ref:`syntax/directives/parsing`
```
../_images/fun-fish.png

Party time!#

A reference from inside: Party time!

A reference from outside: 指令如何解析内容

请注意文本是如何与文档的其余部分整合的，因此也可以在文档的其他地方引用 派对鱼。

嵌套指令#

您可以通过确保外层指令的标记线比内层指令的标记线更长来实现指令的嵌套。例如，将警告嵌套在注释块中，如下所示：

````{note}
The next info should be nested
```{warning}
Here's my warning
```
````

备注

The next info should be nested

警告

Here’s my warning

您可以缩进内部代码栏，只要缩进不超过 3 个空格。否则，它们将被渲染为‘原始代码’块：

````{note}
The warning block will be properly-parsed

   ```{warning}
   Here's my warning
   ```

But the next block will be parsed as raw text

    ```{warning}
    Here's my raw text warning that isn't parsed...
    ```
````

备注

The warning block will be properly-parsed

警告

Here’s my warning

But the next block will be parsed as raw text

```{warning}
Here's my raw text warning that isn't parsed...
```

如果您愿意，这真的可以被玩坏 ;-)

``````{note}
The next info should be nested
`````{warning}
Here's my warning
````{admonition} Yep another admonition
```python
# All this fuss was about this boring python?!
print('yep!')
```
````
`````
``````

备注

The next info should be nested

警告

Here’s my warning

Yep another admonition

# All this fuss was about this boring python?!
print('yep!')

Markdown 友好型指令#

想要使用在标准 Markdown 编辑器中也能正确渲染的语法吗？请参阅 扩展语法选项。

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

备注

This text is standard Markdown

1.2.  Roles - an in-line extension point#

角色（Roles）与指令（directives）类似——它们允许您定义任意新功能，但它们是 内联 使用的。要定义内联角色，请使用以下形式：

MyST

reStructuredText

 
{role-name}`role content`

:role-name:`role content`

例子：

Since Pythagoras, we know that {math}`a^2 + b^2 = c^2`

Since Pythagoras, we know that \(a^2 + b^2 = c^2\)

您可以使用角色来引用书中的公式和其他内容。例如：

```{math} e^{i\pi} + 1 = 0
:label: euler
```

Euler's identity, equation {math:numref}`euler`, was elected one of the
most beautiful mathematical formulas.
(1)#\[e^{i\pi} + 1 = 0\]

Euler’s identity, equation (1), was elected one of the most beautiful mathematical formulas.

角色如何解析内容#

角色的内容解析方式取决于您所使用的角色。某些角色期望输入内容以改变功能。例如，ref 角色会假定输入内容是对网站其他部分的引用。然而，其他角色可能会使用 MyST 解析器将输入内容解析为普通内容。

某些角色还会根据您传递的内容 扩展其功能。例如，以上述 ref 角色为例，如果您传递这样的字符串：要显示的内容 <myref>，那么 ref 将显示 要显示的内容，并使用 myref 作为查找的引用。

角色如何解析这些内容取决于创建该角色的作者。

2.  仅限 MyST 的角色#

本节包含有关与 MyST 解析器 Sphinx 扩展捆绑在一起的特殊角色和指令的信息。

2.1.  插入日期和阅读时间#

Added in version 0.14.0: sub-ref 角色与字数统计。

您可以通过替换定义将 “last updated” 日期和预计阅读时间插入到文档中，这些定义可以通过 sub-ref 角色访问。

例子：

> {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read

2024 年 12 月 27 日 | 740 words | 4 min read

today 会被替换为文档解析时的日期，其格式由 today_fmt 设置，或者如果在配置文件中设置了 today 变量，则使用该变量。

阅读速度是通过 myst_words_per_minute 配置计算的（请参阅 Sphinx 配置选项）。