目录结构

目录结构#

你的书籍结构由一个目录决定。这是一个 YAML 文件（称为 _toc.yml），它定义了 Jupyter Book 用来创建页面顺序和嵌套的结构。

迁移到新的目录结构

在 v0.11 中引入了一个新的目录结构。要将旧的目录结构迁移到新的结构，你有几个选项：

手动迁移你的目录。参见这篇博客文章作为从旧目录结构迁移的一个示例。
使用迁移工具。这将自动从旧目录生成一个新的目录，尽管可能会稍微改变格式。为此，使用以下命令：
```
jupyter-book toc migrate path/to/_toc.yml -o path/to/_toc.yml
```

书籍结构#

目录大体上组织如下：

format: jb-book
root: index
chapters:
- file: path/to/chapter1
- file: path/to/chapter2

以下是对每个键的简要解释：

format:: 定义此目录的结构（例如，如何解释键名）。jb-book 告诉 Jupyter Book 期望使用 chapters 和 parts 术语（详细信息见下文）。
root:: 你的书籍的第一页（即，“根页面”）。它是你书籍 HTML 的着陆页。所有章节/小节的路径将相对于此根文档。
chapters:: 一个条目列表，每个条目对应你书籍的章节。
file:: 一个指向包含章节/小节内容文件的路径。这些路径是相对于 root: 文档的相对路径。

使用章节子小节#

你可以选择将一个章节拆分为多个文件（每个文件构成章节的一个小节）。为此，使用 sections: 配置，如下所示：

format: jb-book
root: index
chapters:
- file: path/to/chapter1
- file: path/to/chapter2
  sections:
  - file: path/to/chapter2/section1

以下是对 sections: 的简要解释：

sections:: 一个条目列表，定义章节的子小节。如果你想将一个章节拆分为多个页面，这很有用。参见标题和章节如何映射到书籍结构获取更多信息。

使用部分来组织章节#

你可以选择将章节组织成部分，通过使用 parts: 键，如下所示：

format: jb-book
root: index
parts:
  - caption: 第一部分名称
    chapters:
    - file: path/to/part1/chapter1
    - file: path/to/part1/chapter2
      sections:
      - file: path/to/part1/chapter2/section1
  - caption: 第二部分名称
    chapters:
    - file: path/to/part2/chapter1
    - file: path/to/part2/chapter2
      sections:
      - file: path/to/part2/chapter2/section1

以下是对 parts: 的简要解释：

parts:: 一个条目列表，每个条目定义一个章节。如果你想使用不同的章节组，这很有用。

文章结构#

你可以构建一个文章（例如，单个页面）而不是整个书籍。你可以从单个源文件或将其拆分为多个文件（类似于你构建书籍的方式）来构建文章的输出。

本节包含更多关于如何做到这一点的信息。

工作进行中

Jupyter Book 的文章构建功能仍在设计和开发中。此功能可能会随着时间的推移而变化！如果你有想法、建议或想提供帮助，请参见贡献指南。

从单个文件构建文章#

你可以使用 jupyter-book 命令为 Jupyter Book 的单个页面生成独立的 HTML 文件，并将其指向一个单个文件而不是一个书籍目录：

jupyter-book build path/to/mypage.ipynb

这将像往常一样构建文件，并将其放置在名为 _build/_page/html/<mypage> 的输出文件夹中。

如果文件相对于 _build 文件夹在子目录中，HTML 将位于 _build/_page/html/<subdirectory-mypage> 文件夹中。

你的页面将被命名为 mypage.html。这对于 Jupyter Book 支持的任何内容源文件都适用。

从多个文件构建文章#

你也可以将一篇文章拆分为多个输入文件（例如，如果你想将小节单独存储）。为此，在你的 _toc.yml 文件中使用 format: jb-article 选项。

例如：

format: jb-article
root: index
sections:
- file: path/to/chapter1
- file: path/to/chapter2

主要的区别在于，jb-book 格式使用 parts: 和 chapters: 语法，而 jb-article 格式仅使用 sections: 语法。

要通过这些文件构建单个HTML页面（而不是每个文件一个页面），请使用singlehtml builder。

例如：

jupyter-book build path/to/book --builder singlehtml

内容条目类型#

您可以提供几种不同类型的条目来指向特定类型的内容。以下是一个快速概览：

file:

指向本地文本文件的路径，该文件定义了此条目的内容（章节、节或子节）。这些路径应相对于您的 _toc.yml 文件。

glob:

一个类似glob的模式，可用于匹配多个本地文件。这些文件将按 glob 发现的顺序收集并插入到您的内容中。

url:

指向网站的外部链接（以 http 或 https 开头）。这将被插入到您书籍的目录中，但不会影响书籍的结构（如编号）。

当提供 title: 条目时，其文本将代替完整的URL使用。

以下是一个展示所有三种类型的示例：

format: jb-book
root: index
chapters:
- file: path/to/chapter1
- url: https://example.com
  title: Example website
- glob: subfolder/other*

从内容文件生成目录#

您可以使用 jupyter-book 从您的书籍文件名生成目录文件。为此，请运行以下命令：

jupyter-book toc from-project path/to/book -f [jb-book/jb-article]

Jupyter Book 将在 mybookpath/ 中搜索任何内容文件，并基于这些文件创建一个 _toc.yml 文件。有几点需要注意：

每个子文件夹中必须至少有一个内容文件。
_toc.yml 中文件的顺序将取决于文件名的字母数字顺序（例如，folder_01 排在 folder_02 之前，apage 排在 b_page 之前）。
如果任何文件夹中有一个名为 index.md 的文件，它将首先列出。

您还可以从书籍的每个文件生成导航栏的标题。如果这样做，请注意，如果文件名以 <integer>_filename.md 开头，则 <integer> 部分将在插入 _toc.yml 之前被删除。

此外，您有几种额外的选项来控制如何生成 _toc.yml 文件。

Usage: jupyter-book toc from-project [OPTIONS] SITE_DIR

  Create a ToC file from a project directory.

Options:
  -e, --extension TEXT            File extensions to consider as documents
                                  (use multiple times)  [default: .rst, .md]
  -i, --index TEXT                File name (without suffix) considered as the
                                  index file in a folder  [default: index]
  -s, --skip-match TEXT           File/Folder names which match will be
                                  ignored (use multiple times)  [default: .*]
  -t, --guess-titles              Guess titles of documents from path names
  -f, --file-format [default|jb-book|jb-article]
                                  The key-mappings to use.  [default: default]
  -h, --help                      Show this message and exit.