Configure the Table of Contents¶

This page covers some of the options you have available to control your book’s behavior via the Table of Contents.

Configure all entries in the TOC¶

To configure options for all entries of your TOC, use the defaults: configuration at the root of your Table of Contents. This configuration will be applied to every list of chapters or sections within your book.

For example:

format: jb-book
root: index
defaults:  # The defaults key will be applied to all chapters and sub-sections
  titlesonly: True
chapters:
- file: path/to/chapter1
- file: path/to/chapter2

Configure a single top-level set of chapters/sections¶

If you’re only using a single list of chapters, and not organizing them into parts, you can configure each with the options: key.

For example:

format: jb-book
root: index
options:  # The options key will be applied to all chapters, but not sub-sections
  numbered: True
chapters:
- file: path/to/part1/chapter1
- file: path/to/part1/chapter2

Configure an individual Part¶

If you are organizing your book into parts (groups of chapters), you can configure each set of chapters separately by providing key: value pairs alongside each part entry, like so:

format: jb-book
root: index
parts:
  - caption: Name of Numbered Part 1
    numbered: True  # Only applies to chapters in Part 1.
    chapters:
    - file: path/to/part1/chapter1
    - file: path/to/part1/chapter2
  - caption: Name of Not-numbered Part 2
    chapters:
    - file: path/to/part2/chapter1
    - file: path/to/part2/chapter2

In this case, the numbered: option would only apply to Part 1, and not Part 2. If you would like numbering across your project you will need to add numbered: true to all parts.

警告

Currently there is no global setting to enable numbered: true across all parts.

You cannot use

defaults:
  numbered: true

as sphinx will issue warnings due to numbered flag being set for substrees. It also causes unexpected output.

Add captions to Parts¶

To add a caption to a Part (so that it shows up in the sidebar, for example) use the caption: option like so:

- caption: My part name
  chapters:
  - file: chapter1
  ...

Specify alternate titles¶

If you’d like to specify an alternate title from the one defined within a file, you may do so with the title: key. For example:

- file: path/to/myfile
  title: My alternate page title

Note that this only applies to the sidebar in the table of contents, it does not change the actual chapter/section title.

Number your chapters and sections¶

You can automatically add numbers to each chapter of your book. To add numbers to all chapters of your book, add the numbered: true flag to your book’s defaults, like so:

format: jb-book
root: intro
options:
  numbered: true
chapters:
  - file: chapter1
  - file: chapter2

Numbers will follow a hierarchy according to the structure defined in your _toc.yml file.

By default, chapter numbering will be continuous between parts (i.e. they will not re-start each section at 1. each time) using an extension called sphinx-multitoc-numbering.

小技巧

To restart chapter numbering between parts, use the following setting in your _config.yml file:

html:
  use_multitoc_numbering: false

This was the default behaviour prior to jupyter-book<0.11.2.

Limit the depth of numbering

If you’d like to limit the depth of numbering, use an integer for the numbered flag. This will be the depth of sub-sections to continue numbering. For example, numbered: 3.

If you’d like to number subsets of chapters, group them into parts and apply the numbered: true flag to the parts whose chapters you wish to be numbered.

For example:

format: jb-book
root: intro
parts:
- caption: Part 1
  numbered: true  # Only part 1 will be numbered
  chapters:
  - file: part1/chapter1
- caption: Part 2
  chapters:
  - file: part2/chapter1

A few caveats about numbering

Jupyter Book relies on Sphinx to apply section numbering, and this has a few quirks to it. Here are a few gotchas:

Numbering applies to sections of your page. Note that when you add numbering to a section, it will add numbers to each header in a file. This means that if you have headers in a top-level section, then its headers will become numbered as sub-sections, and any other files underneath it will begin as third-level children. See How headers and sections map onto to book structure for more information.

jupyter-book < 0.11.2

Numbering resets across parts. If you specify groups of sections via - part: entries, then numbering will restart between them. That means if you have two - part: entries with 2 pages each, you will have two sets of 1. and 2. sections, one for each part.

Add a table of contents to a page’s content¶

If you’d like to add a table of contents for the sub-sections of a page within the page content (in-line with the content on the page), you may do so by using the {tableofcontents} directive. You can use it like so:

```{tableofcontents}
```

See the source of the content types page for an example.

Control the depth of the displayed Table of Contents¶

To control the maximum depth of the Table of Contents that you insert, use the maxdepth: option in your _toc.yml file. For example:

- caption: My part name
  maxdepth: 2  # The displayed Table of Contents will only have two levels
  chapters:
  - file: chapter1
  ...

Exclude pages from your build¶

By default, Jupyter Book will build all content files that are found in your book’s folder, even if they are not specified in _toc.yml (and will raise a warning if it finds a file that isn’t listed there).

If you’d like Jupyter Book to skip a file entirely, you can do so with the following configuration in _config.yml:

exclude_patterns: [pattern1/*, path/to/myfile.ipynb]

Any files that match the patterns described there will be excluded from the build. If you’d like to exclude files from being executed but still wish for them to be built by Jupyter Book, see Exclude files from execution.

Disable building files that aren’t in the Table of Contents¶

By default, Jupyter Book will build all files that are in your book’s folder, regardless of whether they are specified in the Table of Contents. To disable this behavior and only build files that are specified in the TOC, use the following pattern in _config.yml:

only_build_toc_files: true

Note that files that are in hidden folders (e.g. in .github or .venv) will still be built even if they are not specified in the TOC. You should exclude these files explicitly.