基础

基础#

默认文件格式#

除了以 Sphinx 默认格式 RestructuredText (.rst) 编写外，加载 myst_nb 还将解析：

Markdown 文件 (.md)
Jupyter notebooks (.ipynb)
MyST-NB 基于文本的笔记本（.md + top-matter）

自定义文件扩展名#

您可以使用 conf.py 中的 source_suffix 选项更改 MyST-NB 解析的文件扩展名，例如：

extensions = ["myst_nb"]
source_suffix = {
    '.rst': 'restructuredtext',
    '.ipynb': 'myst-nb',
    '.myst': 'myst-nb',
}

其他笔记本格式#

请参阅定制格式部分，了解如何将其他笔记本格式集成到您的构建中，以及与 jupytext 的集成。

MyST Markdown#

对于所有文件格式，Markdown 编写是 MyST-NB 的支柱。默认情况下，启用了 MyST 风格的 Markdown，它扩展了 CommonMark，并提供了受 RST 启发的语法，以满足技术写作所需的额外功能。

特别是 MyST 添加了目标、角色和指令语法，允许您利用所有可用的 Docutils/Sphinx 功能：

RestructuredText

.. _target:
Header
------

:role-name:`content`

.. directive-name:: argument
   :parameter: value

   content

MyST Markdown

(target)=
# Header

{role-name}`content`

```{directive-name} argument
:parameter: value

content
```

参见

请参阅 Jupyter Notebooks 部分，了解有关如何编写 Jupyter 笔记本的更多详细信息。

基于文本的笔记本#

MyST-NB 基于文本的笔记本是一种特殊格式，用于将 Jupyter 笔记本存储在文本文件中。它们直接映射到笔记本文件，而不直接存储代码执行输出。

要将 Markdown 文件指定为基于文本的笔记本，请将以下 top-matter 添加到文件的开头：

---
file_format: mystnb
kernelspec:
  name: python3
---

kernelspec.name 应与环境中安装的 Jupyter 内核相关。

MyST-NB 还将识别 jupytext top-matter，例如：

---
kernelspec:
  name: python3
  display_name: python3
jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: '0.13'
    jupytext_version: 1.13.8
---

然后通过 code-cell 指令指定代码单元：

```{code-cell}
:tags: [my-tag]

print("Hello world!")
```

并且可以通过 +++ 分隔符语法将 Markdown 拆分为单元：

Markdown cell 1

+++ {"tags": ["my-tag"]}

Markdown cell 2, with metadata tags

参见

请参阅基于文本的笔记本部分，了解有关基于文本的笔记本以及与 jupytext 集成的更多详细信息。

配置#

MyST-NB 的解析、执行和渲染可以在三个级别的特异性上进行配置；全局、每个文件和每个笔记本单元，最具体的配置优先。

请参阅配置部分，了解有关如何配置 MyST-NB 的更多详细信息。

基础

目录

基础#