MyST 中的指令与角色

5.3. MyST 中的指令与角色#

MyST同StrucuturedText一样实现了指令与角色，以扩展标识语言之外的功能。

5.3.1. MyST Markdown 指令写法#

指令语法是用三重反引号和花括号定义的。它实际上是一个用大括号括住语言的代码块，以及代替语言名称的指令名称。 它类似于 RMarkdown 定义“可运行单元格”的方式。这是基本结构：

MyST 写法 1

MyST 写法 2

reStructuredText

 
```{directivename} arguments
---
key1: val1
key2: val2
---
This is
directive content
```

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

This is
directive content
```

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

   This is
   directive content

使用 YAML frontmatter#

指令第一行之后的 YAML 前言块将被解析为指令的选项。这需要用 --- 线包围。 两者之间的所有内容都将由 YAML 解析并作为关键字参数传递给您的指令。 如果您的指令有很多选项，或者有一个非常长的值（例如，跨越多行），那么您还可以将选项包装在行中 --- 并将它们写为 YAML。

````
```{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')
```
````

```{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')
```

带有 : 字符的简写选项#

这种写法最接近 reST 语法，无论读者是否在学习 MyST Markdown 之前学习过 reST 标记语言，笔者个人都推荐使用这种语法， 因为这样可以使得我们能够快速切换两种语言的指令的写法。

```{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')

MyST Markdown 与 reST 标记语言的切换

由本文章开篇第一部分的 MyST Markdown 写法2 与 reST 比较可知， reST 标记语言的原生指令甚至是扩展指令都是可以和在 MyST Markdown 和 reST 两个语言中相互切换使用的。

5.3.2. 指令如何解析指令内容#

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

eval-rst 指令#

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

```{eval-rst}
.. figure:: ./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/guide/parsing`
```
_images/fun-fish3.png

图 5.3.1 Party time!#

A reference from inside: Party time!

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

当然，我们还可以通过 eval-rst 指令 实现 将 rST 文件包含到 Markdown 文件中。

5.3.3. 嵌套指令#

您可以通过确保与最外层指令对应的刻度线长于内部指令的刻度线来嵌套指令。例如，在注释块中嵌套警告，如下所示：

MyST Markdown

渲染结果

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

注解

The next info should be nested

警告

Here’s my warning

注解

只要保证最外层指令对应的刻度线长于内部指令的刻度线，那么指令可以一直嵌套（虽然没有必要），就已上方的语法和渲染结果的对比来说，笔者使用了六个 ` 来包裹内容。

如果您想在 Markdown 中显示反引号，可以通过将它们嵌套在更长的反引号中来实现。Markdown 会将最外面的反引号视为“原始”块的边缘，里面的所有内容都会显示出来。

可以缩进内部代码围栏，只要它们的缩进不超过 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...
```

5.3.4. Markdown 友好指令#

想使用在标准 Markdown 编辑器中正确呈现的语法吗？请参阅 扩展语法选项。

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

注解

This text is standard Markdown

5.3.5. 角色#

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

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\)

5.3.6. 额外的 MyST Markdown 语法#

该表描述了rST和MyST的等价项:

Type

MyST

reStructuredText

Math shortcuts

$x^2$

N/A

指令可选项

 
---
key: val
---

:key: val

注释

% comment

.. comment

label 标签

(mytarget)=

.. _mytarget:

5.3.7. 目标和交叉引用#

目标用于定义您可以在文档中的其他地方引用的自定义锚点。它们通常放在章节标题之前，以便您可以轻松地参考它们。

作为测试的引用标题#

在 MyST Markdown 中，目标标头使用以下语法定义：

(header_target)=

然后可以使用 ref 内联角色引用它们：

作为测试的引用标题

默认情况下，引用将使用目标的文本（例如部分标题），但您也可以直接指定文本：

my text

例如，请参阅此参考：目标和交叉引用，这是返回此页面顶部的参考：返回顶部。

使用 Markdown 的链接语法#

[my text](header_target)

如果您希望将目标的标题插入到您的文本中，您可以将 Markdown 链接的“文本”部分留空。 例如，这个 markdown: [](header.md) 。

    [](./optional-syntax.md)

    [](myst-opational-syntax)

运行效果如下所示：

<no title>

可选的 MyST 扩展语法

5.3.8. 注释#

通过将 % 字符放在行首来添加注释，这将防止该行被解析为输出文档。

例如，这段代码：

% my comment

在下面，但它不会被解析到文档中。

参见

MyST Markdown 依旧遵循原来 Markdown 语法，所以 Markdown 的注释语法对 MyST Markdown 起作用。

例如，这段代码：

<!-- my comment -->

在下面，但它不会被解析到文档中。

重要

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

a line
% a comment
another line

a line

another line

5.3.9. 块中断#

可以通过放置 +++ 在一行的开头来添加块中断。 该构造的预期用例是映射到基于单元格的文档格式，如 Jupyter Notebooks，以指示新的文本单元格。 它不会出现在呈现的文本中，而是存储在内部文档结构中供开发人员使用。

例如，这段代码：

+++ some text

效果如下，虽然实际的代码如上显示，但在解析结果中看不到。

目录