配置

配置#

MyST 解析可以在全局和单个文档级别进行配置，最具体的配置优先。

1. 全局配置#

通过在 Sphinx conf.py 文件中指定变量，可以在全局级别覆盖默认配置。所有 myst_parser 全局配置变量都以 myst_ 为前缀，例如：

myst_enable_extensions = ["deflist"]

参见

Docutils 中的配置，请参阅单页构建部分。

名称	类型	描述
`myst_commonmark_only`	`bool`	使用严格的 CommonMark 解析器（默认：`False`）。
`myst_gfm_only`	`bool`	使用严格的 Github Flavoured Markdown 解析器（默认：`False`）。
`myst_enable_extensions`	`set[str]`	启用语法扩展（默认：`set()`）。
`myst_disable_syntax`	`collections.abc.Iterable[str]`	禁用 Commonmark 语法元素（默认：`[]`）。
`myst_all_links_external`	`bool`	将所有链接解析为简单超链接（默认：`False`）。
`myst_links_external_new_tab`	`bool`	在新标签页中打开所有外部链接（默认：`False`）。
`myst_url_schemes`	`list[str] \| dict[str, None \| str \| dict]`	转换为外部链接的 URI 方案（默认：`{'http': None, 'https': None, 'mailto': None, 'ftp': None}`）。
`myst_ref_domains`	`collections.abc.Iterable[str] \| None`	用于搜索链接引用的 Sphinx 域名（默认：`None`）。
`myst_fence_as_directive`	`set[str]`	将特定语言名称的代码栏解释为指令。这对于像 dot 和 mermaid 这样的代码栏以及与其他 Markdown 渲染器的互操作性非常有用。（默认：`set()`）
`myst_number_code_blocks`	`collections.abc.Sequence[str]`	为这些语言的代码块添加行号（默认：`[]`）。
`myst_title_to_header`	`bool`	将 front-matter 中的 `title` 字段转换为 H1 标题（默认：`False`）。
`myst_heading_anchors`	`int`	为 HTML 锚点分配的标题级别深度（默认：`0`）。
`myst_heading_slug_func`	`None \| Callable[[str], str] \| str`	用于创建标题锚点的函数，或 Python 导入路径，例如 `my_package.my_module.my_function` （默认：`None`）。
`myst_html_meta`	`dict[str, str]`	HTML meta tags (default: `{}`)
`myst_footnote_sort`	`bool`	将所有脚注移动到文档末尾，并按引用顺序排序（默认：`True`）。
`myst_footnote_transition`	`bool`	在排序后的脚注前放置 transition（默认：`True`）。
`myst_words_per_minute`	`int`	用于阅读速度计算（默认：`200`）。

1.1. 插件#

特定于语法插件的配置：

名称	类型	描述
`myst_substitutions`	`dict[str, Any]`	替换：替换映射（默认：`{}`）。
`myst_sub_delimiters`	`tuple[str, str]`	替换：替换分隔符（默认：`('{', '}')`）。
`myst_linkify_fuzzy_links`	`bool`	linkify：识别没有模式前缀的 URL（默认：`True`）。”
`myst_dmath_allow_labels`	`bool`	dollarmath：解析 `$$...$$ (label)` （默认：`True`）。
`myst_dmath_allow_space`	`bool`	dollarmath：允许在 $ ... $ 中使用初始/最终空格（默认：`True`）。
`myst_dmath_allow_digits`	`bool`	dollarmath：允许初始/最终数字 `1$ ...$2` （默认：`True`）。
`myst_dmath_double_inline`	`bool`	dollarmath：解析内联 `$$ ... $$` （默认：`False`）。
`myst_update_mathjax`	`bool`	dollarmath：更新 sphinx.ext.mathjax 配置以忽略 `$` 分隔符（默认：`True`）。
`myst_mathjax_classes`	`str`	dollarmath：添加到数学 HTML 的 MathJax 类（默认：`'tex2jax_process\|mathjax_process\|math\|output_area'`）。
`myst_enable_checkboxes`	`bool`	tasklist：启用复选框（默认：`False`）。

2. Frontmatter（局部）配置#

Frontmatter 允许您指定关于单个文档应如何行为或渲染的元数据和选项。它是文档开头的 YAML 块，例如在 jekyll 中使用。文档应以三个或更多 --- 标记开头，YAML 解析直到找到结束的 --- 标记：

---
key1: value
key2: [value1, value2]
key3:
  subkey1: value
---

参见

前言还用于替换语法扩展，并且可以用于存储博客发布的信息（参见 ablog 的 myst-parser 支持）。

以下配置变量可以在文档前言中设置。这些可以在文档前言中的 myst 键下设置，例如：

---
myst:
  enable_extensions: ["deflist"]
---

名称	类型	描述
`commonmark_only`	`bool`	使用严格的 CommonMark 解析器（默认：`False`）。
`gfm_only`	`bool`	使用严格的 Github Flavoured Markdown 解析器（默认：`False`）。
`enable_extensions`	`set[str]`	启用语法扩展（默认：`set()`）。
`disable_syntax`	`collections.abc.Iterable[str]`	禁用 Commonmark 语法元素（默认：`[]`）。
`all_links_external`	`bool`	将所有链接解析为简单超链接（默认：`False`）。
`links_external_new_tab`	`bool`	在新标签页中打开所有外部链接（默认：`False`）。
`url_schemes`	`list[str] \| dict[str, None \| str \| dict]`	转换为外部链接的 URI 方案（默认：`{'http': None, 'https': None, 'mailto': None, 'ftp': None}`）。
`ref_domains`	`collections.abc.Iterable[str] \| None`	用于搜索链接引用的 Sphinx 域名（默认：`None`）。
`fence_as_directive`	`set[str]`	将特定语言名称的代码栏解释为指令。这对于像 dot 和 mermaid 这样的代码栏以及与其他 Markdown 渲染器的互操作性非常有用。（默认：`set()`）
`number_code_blocks`	`collections.abc.Sequence[str]`	为这些语言的代码块添加行号（默认：`[]`）。
`title_to_header`	`bool`	将 front-matter 中的 `title` 字段转换为 H1 标题（默认：`False`）。
`heading_anchors`	`int`	为 HTML 锚点分配的标题级别深度（默认：`0`）。
`html_meta`	`dict[str, str]`	HTML meta tags (default: `{}`)
`footnote_sort`	`bool`	将所有脚注移动到文档末尾，并按引用顺序排序（默认：`True`）。
`footnote_transition`	`bool`	在排序后的脚注前放置 transition（默认：`True`）。
`words_per_minute`	`int`	用于阅读速度计算（默认：`200`）。

2.1. Setting HTML Metadata#

front-matter 可以包含特殊键 html_meta；字典，包含要添加到生成的 HTML 中的 <meta> 元素数据。这等同于使用 meta 指令。

HTML 元数据也可以通过 myst_html_meta 变量在 conf.py 中全局添加，在这种情况下，它将添加到所有 MyST 文档中。对于每个文档，myst_html_meta 字典将由文档级别的前言 html_meta 更新，且前言优先。

Sphinx 配置

language = "en"
myst_html_meta = {
    "description lang=en": "metadata description",
    "description lang=fr": "description des métadonnées",
    "keywords": "Sphinx, MyST",
    "property=og:locale":  "en_US"
}

MyST Front-Matter

---
myst:
  html_meta:
    "description lang=en": "metadata description"
    "description lang=fr": "description des métadonnées"
    "keywords": "Sphinx, MyST"
    "property=og:locale": "en_US"
---

RestructuredText

.. meta::
   :description lang=en: metadata description
   :description lang=fr: description des métadonnées
   :keywords: Sphinx, MyST
   :property=og:locale: en_US

HTML 输出

<html lang="en">
  <head>
    <meta content="metadata description" lang="en" name="description" xml:lang="en" />
    <meta content="description des métadonnées" lang="fr" name="description" xml:lang="fr" />
    <meta name="keywords" content="Sphinx, MyST">
    <meta content="en_US" property="og:locale" />

2.2. 插件#

特定于语法插件的配置：

名称	类型	描述
`substitutions`	`dict[str, Any]`	替换：替换映射（默认：`{}`）。
`sub_delimiters`	`tuple[str, str]`	替换：替换分隔符（默认：`('{', '}')`）。
`linkify_fuzzy_links`	`bool`	linkify：识别没有模式前缀的 URL（默认：`True`）。”
`dmath_allow_labels`	`bool`	dollarmath：解析 `$$...$$ (label)` （默认：`True`）。
`dmath_allow_space`	`bool`	dollarmath：允许在 $ ... $ 中使用初始/最终空格（默认：`True`）。
`dmath_allow_digits`	`bool`	dollarmath：允许初始/最终数字 `1$ ...$2` （默认：`True`）。
`dmath_double_inline`	`bool`	dollarmath：解析内联 `$$ ... $$` （默认：`False`）。
`enable_checkboxes`	`bool`	tasklist：启用复选框（默认：`False`）。

3. List of syntax extensions#

全部细节见语法插件部分。

amsmath: 启用对 amsmath LaTeX 方程的直接解析。
attrs_inline: 启用内联属性解析，详见此处。
colon_fence: 启用使用 ::: 分隔符的代码栏，详见此处。
deflist: 启用定义列表，详见此处。
dollarmath: 启用对 $ 和 $$ 封装数学的解析。
fieldlist: 启用字段列表，详见此处。
html_admonition: 将 <div class="admonition"> 元素转换为 sphinx 警告节点，详见 HTML 警告语法。
html_image: 将 HTML <img> 元素转换为 sphinx 图像节点，详见此处。
linkify: 自动识别‘裸’网页 URL 并添加超链接。
replacements: 自动转换一些常见的排版文本。
smartquotes: 自动将标准引号转换为其开/关变体。
strikethrough: 启用删除线语法，详见此处。
substitution: 替换键，详见此处。
tasklist: 在列表项的开头添加复选框，详见此处。

4. 构建警告#

以下列出了在构建过程中可能发出的 MyST 特定警告。这些将附加到警告消息的末尾（另请参阅 show_warning_types），例如：

WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]

一般来说，如果您的构建日志中有任何警告，您应该修复它们，或者如果您认为警告是错误的，请提出问题。

然而，在某些情况下，如果您希望抑制警告，可以使用 suppress_warnings 配置选项，例如：

suppress_warnings = ["myst.header"]

或者对于 docutils CLI 使用 --myst-suppress-warnings="myst.header"。

myst.deprecated：已弃用的用法。
myst.not_supported：docutils 中尚未支持的功能。
myst.render：渲染方法未实现。
myst.topmatter：读取前言时出现问题。
myst.duplicate_def: Duplicate Markdown reference definition.
myst.duplicate_def：重复的 Markdown 引用定义。
myst.directive_parse：解析指令时出现问题。
myst.directive_option：解析指令选项时出现问题。
myst.directive_comments：指令选项包含 # 注释，未来版本可能不支持。
myst.directive_body：解析指令主体时出现问题。
myst.directive_unknown：未知指令。
myst.role_unknown: 未知角色。
myst.xref_ambiguous: 交叉引用找到多个目标。
myst.xref_missing: 交叉引用未找到目标。
myst.inv_retrieval: 检索或加载库存失败。
myst.iref_missing: 库存引用未找到目标。
myst.iref_ambiguous: 库存引用找到多个目标。
myst.domains: 找到一个旧域，该域不支持 resolve_any_xref。
myst.heading_slug: 计算标题 slug 时出错。
myst.strikethrough: 删除线警告，因为仅在 HTML 中实现。
myst.html: HTML 无法解析。
myst.attribute: 无效的属性值。
myst.substitution: 替换无法解析。

配置

目录

配置#