Structure the Table of Contents¶

Your book’s structure is determined by a Table of Contents. This is a YAML file (called _toc.yml) that defines a structure that Jupyter Book uses to create the order and nesting of pages.

Migrate to the new Table of Contents structure

A new Table of Contents structure was introduced in v0.11. To migrate your old TOC structure to the new structure, you have a few options:

Manually migrate your TOC. See this blog post for one example migration from an old TOC structure.
Use the migration tool. This automatically generates a new TOC from your old one, though may alter the formatting slightly. To do so, use the following command:
```
jupyter-book toc migrate path/to/_toc.yml -o path/to/_toc.yml
```

Structure of a Book¶

The table of contents is broadly organized like so:

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

Here is a brief explanation of each key:

format:: Defines the structure of this Table of Contents (e.g., how to interpret the key names). jb-book tells Jupyter Book to expect chapters and parts terminology (see below for details).
root:: The first page of your book (aka, the “root page”). It is the landing page for the HTML of your book.
chapters:: A list of entries, each of which maps onto chapters of your book.

Use chapter sub-sections¶

You may optionally split a chapter across multiple files (each making up a section of the chapter). To do so, use the sections: configuration, like so:

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

Here’s a brief explanation of sections:

sections:: A list of entries that define sub-sections of a chapter. This is useful if you’d like to split a chapter across multiple pages. See 标题和章节如何映射到书的结构 for more information.

Use parts to organize chapters¶

You may optionally organize your chapters into parts, by using the parts: key like so:

format: jb-book
root: index
parts:
  - caption: Name of Part 1
    chapters:
    - file: path/to/part1/chapter1
    - file: path/to/part1/chapter2
      sections:
      - file: path/to/part1/chapter2/section1
  - caption: Name of Part 2
    chapters:
    - file: path/to/part2/chapter1
    - file: path/to/part2/chapter2
      sections:
      - file: path/to/part2/chapter2/section1

Here’s a brief explanation of parts:

parts:: A list of entries, each of which defines a chapter. This is useful if you’d like to use different groups of chapters.

Structure of an Article¶

You can build an article (e.g., a single page) rather than an entire book. You can build outputs for an article from a single source file, or split it up across multiple files (similar to how you’d structure a book).

This section contains more information about how to do this.

Work in progress

Article building functionality for Jupyter Book is still under design and development. This functionality may change over time! If you have ideas, suggestions, or would like to help out, please see the contributing guide.

Build an article from a single file¶

You can generate a standalone HTML file for a single page of the Jupyter Book using the jupyter-book command, and pointing it to a single file instead of a book’s directory:

jupyter-book build path/to/mypage.ipynb

This will build the file as usual, and place it in an output folder called _build/_page/html/<mypage>.

If the file is in a subdirectory relative to the _build folder, the HTML will be in a _build/_page/html/<subdirectory-mypage> folder.

Your page will be called mypage.html. This will work for any content source file that is supported by Jupyter Book.

Build an article from multiple files¶

You may also split an article across multiple input files (e.g., if you’d like to store sections separately). To do so, use the format: jb-article option in your _toc.yml file.

For example:

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

The primary difference is that the jb-book format uses parts: and chapters: syntax, while the jb-article format uses sections: syntax alone.

Types of content entries¶

There are several types of entries that you may provide in order to point to specific types of content. Here is a quick overview:

file:

A path that points to a local text file, which defines the content of this entry (the chapter, section, or sub-section). These paths should be relative to your _toc.yml file.

glob:

A glob-like pattern that can be used to match against multiple local files. Each of these files will be collected and inserted into your content, in the order that glob discovers them.

url:

An external link to a website (starting with http or https). This will be inserted into your book’s Table of Contents, though it will not affect your book’s structure (like numbering).

When a title: entry is provided its text is used instead of the full URL.

Here is an example to show all three types:

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

Generate a Table of Contents from content files¶

You can use jupyter-book to generate a table of contents file from your book using the filenames of your book’s content. To do so, run the following command

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

Jupyter Book will search mybookpath/ for any content files and create a _toc.yml file out of them. There are a few considerations to keep in mind:

Each sub-folder must have at least one content file inside it
The ordering of files in _toc.yml will depend on the alphanumeric order of the filenames (e.g., folder_01 comes before folder_02, and apage comes before b_page)
If there is a file called index.md in any folder, it will be listed first.

You may also generate navigation bar titles from each file of your book. If you do so, note that if the file name begins with <integer>_filename.md, then the <integer> part will be removed before it is inserted into _toc.yml.

In addition, you have a few extra options for controlling how the _toc.yml file is generated.

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.