Structure the Table of Contents
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
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:
Defines the structure of this Table of Contents (e.g., how to interpret the key names).
jb-booktells Jupyter Book to expect
partsterminology (see below for details).
The first page of your book (aka, the “root page”). It is the landing page for the HTML of your book. All paths for chapters/sections will be relative to this root document.
A list of entries, each of which maps onto chapters of your book.
A path to a file that contains the content for a chapter / section. These paths are _relative to the
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
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 How headers and sections map onto to book structure 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
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
If the file is in a subdirectory relative to the
_build folder, the HTML will be in a
Your page will be called
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
format: jb-article root: index sections: - file: path/to/chapter1 - file: path/to/chapter2
The primary difference is that the
jb-book format uses
chapters: syntax, while the
jb-article format uses
sections: syntax alone.
To build a single HTML page from these files (rather than one page per file), use the singlehtml builder.
jupyter-book build path/to/book --builder singlehtml
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:
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
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
An external link to a website (starting with
https). This will be inserted into your book’s Table of Contents, though it will not affect your book’s structure (like numbering).
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.ymlwill depend on the alphanumeric order of the filenames (e.g.,
If there is a file called
index.mdin 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> part will be removed before it is inserted into
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.