配置目录#
本页介绍了一些通过目录控制书籍行为的可用选项。
配置目录中的所有条目#
要为目录中的所有条目配置选项，请在目录的根目录中使用 defaults: 配置。此配置将应用于书籍中的每个章节或小节列表。
例如：
format: jb-book
root: index
defaults: # 默认键将应用于所有章节和小节
titlesonly: True
chapters:
- file: path/to/chapter1
- file: path/to/chapter2
配置单个顶级章节/小节集合#
如果您只使用一个章节列表，并且不将其组织成部分，则可以使用 options: 键来配置单个章节组。
例如：
format: jb-book
root: index
options: # 选项键将应用于所有章节，但不应用于小节
numbered: True
chapters:
- file: path/to/part1/chapter1
- file: path/to/part1/chapter2
Note
如果您使用 parts，则 options: 键无效。
您应单独配置每个部分（见下文）。
配置一个或多个部分#
如果您将书籍组织成部分（章节组），请通过在每个 part 条目旁边提供 key: value 对来配置每个部分，如下所示：
format: jb-book
root: index
parts:
- caption: 编号部分 1 的名称
numbered: True # 仅适用于部分 1 中的章节。
chapters:
- file: path/to/part1/chapter1
- file: path/to/part1/chapter2
- caption: 未编号部分 2 的名称
chapters:
- file: path/to/part2/chapter1
- file: path/to/part2/chapter2
在这种情况下，numbered: 仅适用于部分 1，而不适用于部分 2。如果您希望所有部分都编号，则需要将 numbered: true 添加到所有 parts 条目中。
Warning
目前没有全局设置来启用所有部分的 numbered: true。
您不能使用
defaults:
numbered: true
因为 Sphinx 会因为为子树设置了 numbered 标志而发出警告。它还会导致意外输出。
为部分添加标题#
要为部分添加标题（例如，使其显示在侧边栏中），请使用 caption: 选项，如下所示：
- caption: 我的部分名称
chapters:
- file: chapter1
...
指定备用标题#
如果您想指定一个与文件中定义的标题不同的备用标题，可以使用 title: 键。例如：
- file: path/to/myfile
title: 我的备用页面标题
请注意，这仅适用于目录中的侧边栏，不会更改实际的章节/小节标题。
为章节和小节编号#
您可以自动为书籍的章节编号。编号将根据 _toc.yml 文件中定义的结构按层次排列。
为单个章节组编号#
如果您的书籍使用单个章节集（即没有部分），请使用 numbered: true 标志为它们编号，如下所示：
format: jb-book
root: intro
options:
numbered: true
chapters:
- file: chapter1
- file: chapter2
为一个或多个部分编号#
如果使用一个或多个部分，请为每个部分添加 numbered: true 选项。例如，为两部分书籍的所有部分编号：
format: jb-book
root: intro
parts:
- caption: 第一部分
numbered: true
chapters:
- file: part1/chapter1
- caption: 第二部分
numbered: true
chapters:
- file: part2/chapter1
仅对书籍的第二部分编号：
format: jb-book
root: intro
parts:
- caption: 第一部分
chapters:
- file: part1/chapter1
- caption: 第二部分
numbered: true # 仅第二部分编号
chapters:
- file: part2/chapter1
在部分之间重新编号#
默认情况下，章节编号将在部分之间连续（即它们不会每次都从 1. 重新开始），使用名为 sphinx-multitoc-numbering 的扩展。
要在部分之间重新编号章节，请在 _config.yml 文件中使用以下设置：
html:
use_multitoc_numbering: false
限制编号的深度#
如果您想限制编号的深度，请为 numbered 标志使用整数。这将是继续编号的子节深度。例如，numbered: 3。
关于编号的几个注意事项
Jupyter Book 依赖于 Sphinx 来应用章节编号，这有一些小问题。以下是一些注意事项：
编号适用于页面的_部分_。 请注意，当您为章节添加编号时，它将为文件中的每个标题添加编号。这意味着，如果您在顶级章节中有标题，则其标题将作为子章节编号，并且其下的任何_文件_都将编号为子章节。 将以第三级子项开始。更多信息请参见标题和章节如何映射到书籍结构。
jupyter-book < 0.11.2
编号在各部分间重置。 如果你通过
- part:条目指定章节组，那么编号将在它们之间重新开始。这意味着如果你有两个包含两页内容的- part:条目，你将有两个1.和2.章节集，每部分各一个。
在页面内容中添加目录#
如果你想为页面的小节添加目录，并在页面内容中（与页面内容内联）显示，可以使用 {tableofcontents} 指令。你可以这样使用：
```{tableofcontents}
```
请参见内容类型页面的源码作为示例。
控制显示的目录深度#
要控制插入的目录的最大深度，请在 _toc.yml 文件中使用 maxdepth: 选项。例如：
- caption: 我的部分名称
maxdepth: 2 # 显示的目录将只有两个级别
chapters:
- file: chapter1
...
添加页面内目录#
页面内目录显示当前页面的章节（与 _toc.yml 中列出的子页面不同，由上述 {tableofcontents} 指令插入）。
要插入页面内目录，请使用 {contents} 指令。例如，要插入当前页面所有章节的列表（包括页面标题）：
# 页面标题
```{contents}
```
默认情况下，{contents} 指令将包括当前页面中的所有标题级别，包括标题级别 1（即页面标题）。
添加特定章节的目录列表#
要仅列出特定父章节的小节标题，请在 {contents} 指令中添加 :local: 参数。
例如，要仅列出页面上的第二级章节内容（并排除标题）：
# 页面标题
```{contents}
:local:
```
## 章节 1（将被列出）
### 子章节 1（将被列出）
## 章节 2（将被列出）
要仅列出 ## 章节 1 章节的内容：
# 页面标题
## 章节 1（不会被列出）
```{contents}
:local:
```
### 子章节 1（将被列出）
## 章节 1（不会被列出）
限制页面内内容的深度#
你可以使用 :maxdepth: 参数控制页面内目录的深度。
例如，以下用法仅列出标题下的顶级章节，即使存在更深的小节（即 ## 标题，但没有 ### 标题或更深）。
# 页面标题
```{contents}
:local:
:depth: 1
```
排除构建中的页面#
默认情况下，Jupyter Book 会构建在你的书籍文件夹中找到的所有内容文件，即使它们没有在 _toc.yml 中指定（如果发现未列出的文件，会发出警告）。
如果你想让 Jupyter Book 完全跳过某个文件，可以在 _config.yml 中进行以下配置：
exclude_patterns: [pattern1/*, path/to/myfile.ipynb]
任何匹配描述模式的文件都将被排除在构建之外。如果你希望排除文件的执行但仍希望 Jupyter Book 构建它们，请参见 从执行中排除文件。
禁用构建不在目录中的文件#
默认情况下，Jupyter Book 会构建你的书籍文件夹中的所有文件，无论它们是否在目录中指定。
要禁用此行为并仅构建在 TOC 中指定的文件，请在 _config.yml 中使用以下模式：
only_build_toc_files: true
请注意，隐藏文件夹（例如 .github 或 .venv 中的文件）即使未在 TOC 中指定，仍将被构建。你应该显式排除这些文件。