配置

配置#

MyST-NB 可以在三个级别进行配置：全局、每个文件和每个笔记本单元格，最具体的配置优先。

全局配置#

在全局级别覆盖默认配置是通过在 Sphinx conf.py 文件中指定变量来实现的。所有 myst_nb 配置变量都以 nb_ 为前缀，例如：

nb_execution_timeout = 60

阅读#

控制文件的读取方式。

名称	类型	默认值	描述
`nb_custom_formats`	`Dict[str, Tuple[str, dict, bool]]`	`{}`	自定义读取笔记本的格式；后缀 -> 读取器

执行#

此配置用于控制在构建时如何执行 Jupyter Notebooks。

名称	类型	默认值	描述
`nb_kernel_rgx_aliases`	`Dict[str, str]`	`{}`	内核名称正则表达式到替换内核名称的映射（在执行前应用）
`nb_eval_name_regex`	`str`	`'^[a-zA-Z_][a-zA-Z0-...`	匹配 eval 表达式允许值的正则表达式
`nb_execution_mode`	`Literal['off', 'force', 'auto', 'cache', 'inline']`	`'auto'`	笔记本的执行模式
`nb_execution_cache_path`	`str`	`''`	缓存笔记本的文件夹路径（默认：）
`nb_execution_excludepatterns`	`Sequence[str]`	`()`	排除笔记本的 (POSIX) 通配符模式
`nb_execution_timeout`	`int`	`30`	执行超时（秒）
`nb_execution_in_temp`	`bool`	`False`	使用临时文件夹作为执行当前工作目录
`nb_execution_allow_errors`	`bool`	`False`	允许执行期间发生错误
`nb_execution_raise_on_error`	`bool`	`False`	触发异常而不是发出警告
`nb_execution_show_tb`	`bool`	`False`	打印执行错误的跟踪信息到 stderr

阅读#

这些配置选项影响了笔记本的解析和输出呈现的外观。

名称	类型	默认值	描述
`nb_merge_streams`	`bool`	`False`	合并 stdout/stderr 执行输出流
`nb_render_plugin`	`str`	`'default'`	执行输出渲染类的入口点（在组 `myst_nb.output_renderer` 中）
`nb_remove_code_source`	`bool`	`False`	移除代码单元格源
`nb_remove_code_outputs`	`bool`	`False`	移除代码单元格输出
`nb_code_prompt_show`	`str`	`'Show code cell {typ...`	提示展开隐藏的代码单元格 {content\|source\|outputs}
`nb_code_prompt_hide`	`str`	`'Hide code cell {typ...`	提示折叠隐藏的代码单元格 {content\|source\|outputs}
`nb_number_source_lines`	`bool`	`False`	为代码单元格源行编号
`nb_mime_priority_overrides`	`Sequence[Tuple[str, str, Optional[int]]]`	`()`	覆盖 MIME 类型的基本渲染优先级：(构建器名称, MIME 类型, 优先级) 列表
`nb_output_stderr`	`Literal['show', 'remove', 'remove-warn', 'warn', 'error', 'severe']`	`'show'`	标准错误输出的行为
`nb_render_text_lexer`	`str`	`'myst-ansi'`	应用于标准输出/标准错误和文本/纯文本输出的 Pygments 词法分析器
`nb_render_error_lexer`	`str`	`'ipythontb'`	应用于错误/回溯输出的 Pygments 词法分析器
`nb_render_image_options`	`Dict[str, str]`	`{}`	图像输出的选项（class\|alt\|height\|width\|scale\|align）
`nb_render_figure_options`	`Dict[str, str]`	`{}`	图表输出的选项（类\|名称\|标题\|标题在前）
`nb_render_markdown_format`	`Literal['commonmark', 'gfm', 'myst']`	`'commonmark'`	用于 text/markdown 渲染的格式
`nb_ipywidgets_js`	`Dict[str, Dict[str, str]]`	`{'https://cdnjs.clou...`	包含 ipywidgets 的页面上要加载的 Javascript

文件级别配置#

在文件级别覆盖默认配置是通过在文件的元数据中指定变量来实现的，这些变量位于 mystnb 键下。

在 Jupyter 笔记本中，这被添加到笔记本级别的元数据中，例如：

{
  "metadata": {
    "mystnb": {
      "execution_timeout": 60
    }
  }
}

在基于文本的笔记本中，这被添加到 YAML 顶部内容中，例如：

---
file_format: mystnb
mystnb:
  execution_timeout: 60
---

执行#

此配置用于控制在构建时如何执行 Jupyter Notebooks。

名称	类型	默认值	描述
`eval_name_regex`	`str`	`'^[a-zA-Z_][a-zA-Z0-...`	匹配 eval 表达式允许值的正则表达式
`execution_mode`	`Literal['off', 'force', 'auto', 'cache', 'inline']`	`'auto'`	笔记本的执行模式
`execution_cache_path`	`str`	`''`	缓存笔记本的文件夹路径（默认：）
`execution_timeout`	`int`	`30`	执行超时（秒）
`execution_in_temp`	`bool`	`False`	使用临时文件夹作为执行当前工作目录
`execution_allow_errors`	`bool`	`False`	允许执行期间发生错误
`execution_raise_on_error`	`bool`	`False`	触发异常而不是发出警告
`execution_show_tb`	`bool`	`False`	打印执行错误的跟踪信息到 stderr

阅读#

这些配置选项影响了笔记本的解析和输出呈现的外观。

名称	类型	默认值	描述
`merge_streams`	`bool`	`False`	合并 stdout/stderr 执行输出流
`render_plugin`	`str`	`'default'`	执行输出渲染类的入口点（在组 `myst_nb.output_renderer` 中）
`remove_code_source`	`bool`	`False`	移除代码单元格源
`remove_code_outputs`	`bool`	`False`	移除代码单元格输出
`code_prompt_show`	`str`	`'Show code cell {typ...`	提示展开隐藏的代码单元格 {content\|source\|outputs}
`code_prompt_hide`	`str`	`'Hide code cell {typ...`	提示折叠隐藏的代码单元格 {content\|source\|outputs}
`number_source_lines`	`bool`	`False`	为代码单元格源行编号
`mime_priority_overrides`	`Sequence[Tuple[str, str, Optional[int]]]`	`()`	覆盖 MIME 类型的基本渲染优先级：(构建器名称, MIME 类型, 优先级) 列表
`output_stderr`	`Literal['show', 'remove', 'remove-warn', 'warn', 'error', 'severe']`	`'show'`	标准错误输出的行为
`render_text_lexer`	`str`	`'myst-ansi'`	应用于标准输出/标准错误和文本/纯文本输出的 Pygments 词法分析器
`render_error_lexer`	`str`	`'ipythontb'`	应用于错误/回溯输出的 Pygments 词法分析器
`render_image_options`	`Dict[str, str]`	`{}`	图像输出的选项（class\|alt\|height\|width\|scale\|align）
`render_figure_options`	`Dict[str, str]`	`{}`	图表输出的选项（类\|名称\|标题\|标题在前）
`render_markdown_format`	`Literal['commonmark', 'gfm', 'myst']`	`'commonmark'`	用于 text/markdown 渲染的格式

单元格级别配置#

在单元格级别覆盖默认配置是通过在单元格的元数据中指定变量来实现的，这些变量位于 mystnb 键下。

在 Jupyter 笔记本中，这被添加到单元格级别的元数据中，例如：

{
  "cell_type": "code",
  "source": ["print('hello world')"],
  "metadata": {
    "mystnb": {
      "number_source_lines": true
    }
  }
}

在基于文本的笔记本中，这被添加到代码单元格的 YAML 中，例如：

```{code-cell} ipython3
---
mystnb:
  number_source_lines: true
---
print('hello world')
```

名称	类型	默认值	描述
`merge_streams`	`bool`	`False`	合并 stdout/stderr 执行输出流
`remove_code_source`	`bool`	`False`	移除代码单元格源
`remove_code_outputs`	`bool`	`False`	移除代码单元格输出
`code_prompt_show`	`str`	`'Show code cell {typ...`	提示展开隐藏的代码单元格 {content\|source\|outputs}
`code_prompt_hide`	`str`	`'Hide code cell {typ...`	提示折叠隐藏的代码单元格 {content\|source\|outputs}
`number_source_lines`	`bool`	`False`	为代码单元格源行编号
`output_stderr`	`Literal['show', 'remove', 'remove-warn', 'warn', 'error', 'severe']`	`'show'`	标准错误输出的行为
`text_lexer`	`str`	`'myst-ansi'`	应用于标准输出/标准错误和文本/纯文本输出的 Pygments 词法分析器
`error_lexer`	`str`	`'ipythontb'`	应用于错误/回溯输出的 Pygments 词法分析器
`image`	`Dict[str, str]`	`{}`	图像输出的选项（class\|alt\|height\|width\|scale\|align）
`figure`	`Dict[str, str]`	`{}`	图表输出的选项（类\|名称\|标题\|标题在前）
`markdown_format`	`Literal['commonmark', 'gfm', 'myst']`	`'commonmark'`	用于 text/markdown 渲染的格式

单元格标签#

为了方便 Jupyter 界面中的用户，可以通过在单元格元数据中指定标签来实现一些单元格级别的配置。

标签是单元格元数据中 tags 键下的字符串列表，例如：

{
  "cell_type": "code",
  "source": ["print('hello world')"],
  "metadata": {
    "tags": ["my-tag1", "my-tag2"]
  }
}

Tag	描述
`remove-cell`	移除渲染输出中的单元格。
`remove-input`	移除渲染输出中的代码单元格输入/源。
`remove-output`	移除渲染输出中的代码单元格输出。
`remove-stderr`	移除渲染输出中的代码单元格输出 stderr。

此外，对于代码执行，提供了以下标签（通过 nbclient）：

Tag	描述
`skip-execution`	在执行笔记本时跳过此单元格
`raises-exception`	预期代码单元格会引发异常（并继续执行）

Markdown 解析配置#

MyST-NB 解析器源自基础 MyST 解析器，因此所有相同的配置选项都可用。如 MyST 配置选项中所述，完整的全局选项集为：

名称	类型	默认值	描述
`myst_commonmark_only`	`bool`	`False`	使用严格的 CommonMark 解析器
`myst_gfm_only`	`bool`	`False`	使用严格的 GitHub 风格 Markdown 解析器
`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`	`dict[str, myst_parser.config.main.UrlSchemeType \| None]`	`{'http': None, 'http...`	转换为外部链接的 URI 方案
`myst_ref_domains`	`collections.abc.Iterable[str] \| None`	`None`	用于搜索链接引用的 Sphinx 域名
`myst_fence_as_directive`	`set[str]`	`set()`	将代码块解释为指令，适用于某些语言名称。这对于像 dot 和 mermaid 这样的代码块以及与其他 Markdown 渲染器的互操作性非常有用。
`myst_number_code_blocks`	`collections.abc.Sequence[str]`	`[]`	为这些语言的代码块添加行号
`myst_title_to_header`	`bool`	`False`	Convert a `title` field in the front-matter to a H1 header
`myst_heading_anchors`	`int`	`0`	Heading level depth to assign HTML anchors
`myst_heading_slug_func`	`collections.abc.Callable[[str], str] \| None`	`None`	Function for creating heading anchors, or a python import path e.g. `my_package.my_module.my_function`
`myst_html_meta`	`dict[str, str]`	`{}`	HTML meta tags
`myst_footnote_sort`	`bool`	`True`	Move all footnotes to the end of the document, and sort by reference order
`myst_footnote_transition`	`bool`	`True`	Place a transition before sorted footnotes
`myst_words_per_minute`	`int`	`200`	For reading speed calculations
`myst_substitutions`	`dict[str, Any]`	`{}`	Substitutions mapping
`myst_sub_delimiters`	`tuple[str, str]`	`('{', '}')`	Substitution delimiters
`myst_linkify_fuzzy_links`	`bool`	`True`	Recognise URLs without schema prefixes
`myst_dmath_allow_labels`	`bool`	`True`	Parse `$$...$$ (label)`
`myst_dmath_allow_space`	`bool`	`True`	Allow initial/final spaces in $ ... $
`myst_dmath_allow_digits`	`bool`	`True`	Allow initial/final digits `1$ ...$2`
`myst_dmath_double_inline`	`bool`	`False`	Parse inline `$$ ... $$`
`myst_update_mathjax`	`bool`	`True`	Update sphinx.ext.mathjax configuration to ignore `$` delimiters
`myst_mathjax_classes`	`str`	`'tex2jax_process\|mat...`	MathJax classes to add to math HTML
`myst_enable_checkboxes`	`bool`	`False`	Enable checkboxes
`myst_suppress_warnings`	`collections.abc.Sequence[str]`	`[]`	A list of warning types to suppress warning messages
`myst_highlight_code_blocks`	`bool`	`True`	Syntax highlight code blocks with pygments
`myst_inventories`	`dict[str, tuple[str, str \| None]]`	`{}`	Mapping of key to (url, inv file), for intra-project referencing

警告抑制#

当 Sphinx 遇到错误或引发警告时，它将打印生成该错误的文本的位置和源文件。根据您使用的是 Markdown 文件还是 Jupyter Notebook 文件，其工作方式略有不同。

对于 Markdown (.md) 文件，Sphinx 将正确报告与错误或警告相关的行号：

source/path:4: (WARNING/2) Unknown mime type: 'xyz' [mystnb.unknown_mime_type]

对于 Jupyter Notebook (.ipynb) 文件，这些错误也对应于单元格索引。为了允许这一点，使用一种特殊的行号格式，对应于：<CELL_INDEX> * 10000 + LINE_NUMBER。

例如，以下错误对应于单元格 1，第 4 行：

source/path:10004: (WARNING/2) Unknown mime type: 'xyz' [mystnb.unknown_mime_type]

一般来说，如果您的构建记录了任何警告，您应该修复它们，或者如果您认为警告是错误的，请提出 Issue。但是，在某些情况下，如果您希望抑制警告，可以使用 Sphinx suppress_warnings 配置选项。所有 myst-nb 警告都以它们的类型为前缀，可以通过例如以下方式抑制：

suppress_warnings = ["mystnb.unknown_mime_type"]

配置

目录

配置#