标题和章节如何映射到书籍结构

标题和章节如何映射到书籍结构#

Jupyter Book 在底层使用了 Sphinx 文档引擎，它以特定的方式表示书籍的结构。_toc.yml 的结构选择和页面内的标题结构的不同组合将导致书籍整体结构的差异。以下是一些通用的技巧和最佳实践。

Note

这在为书籍章节编号或通过 Latex 生成书籍的 PDF时尤为重要。

章节位于书籍层次结构的顶端。_toc.yml 的顶层包含章节的列表。每个文件的标题将成为章节的标题。

标题映射到章节。Jupyter Book 将你的书籍视为章节的集合，并根据 _toc.yml 的层次结构和页面内的标题层次结构决定这些章节应如何嵌套。在一个文件中，Jupyter Book 发现的第一个 ## 标题将定义该文件中最高级别的章节，而其下的任何 ### 标题将成为子章节（直到遇到另一个 ## 章节）。如果页面是嵌套在其他页面下的，这种行为会有所不同（见下文）。

嵌套文件定义其父章节的子章节。如果你指定的是嵌套在文件下的章节（使用 sections: 键），那么这些章节将在父页面的最后一个标题下开始。

例如，如果你的 _toc.yml 文件如下所示：

format: jb-book
root: myintro
chapters:
- file: chapter1
  sections:
  - file: chapter1section

那么 chapter1section 的章节将在 chapter1 的章节之下开始。chapter1section 中的任何标题将被视为 chapter1 中的“下一级标题”。

换句话说，如果 chapter1 和 chapter1section 看起来像这样：

chapter1.md

# Chapter 1 title

## Chapter 1 second header

chapter1section.md

# Chapter 1 section title

## Chapter 1 section second header

那么你的书籍将这样处理它们：

# Chapter 1 title

## Chapter 1 second header

### Chapter 1 section title

#### Chapter 1 section second header

然而，如果 chapter1.md 有一个额外的三级标题，如下所示：

chapter1.md

# Chapter 1 title

## Chapter 1 second header

### Chapter 1 third header

chapter1section.md

# Chapter 1 section title

## Chapter 1 section second header

那么你的书籍将这样处理它们：

# Chapter 1 title

## Chapter 1 second header

### Chapter 1 third header

#### Chapter 1 section title

##### Chapter 1 section second header

在设计文件结构时请记住这一点。

Tip

一个很好的经验法则是采取以下两种方法之一：

  1. 不要在介绍页中放置标题。这适用于书籍的介绍，也适用于任何章节的介绍。相反，将标题留给内容更丰富的页面，并在需要使用标题的地方使用加粗文本。

  2. 使用扁平的文件列表而不是嵌套文件。这样，每个章节中的章节层次结构仅在单个文件中定义。然而，这意味着你通常会有较长的文件。