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 expectchapters
andparts
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. All paths for chapters/sections will be relative to this root document.
chapters:
A list of entries, each of which maps onto chapters of your book.
file:
A path to a file that contains the content for a chapter / section. These paths are relative to the
root:
document.
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 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 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.
To build a single HTML page from these files (rather than one page per file), use the singlehtml builder.
For example:
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:
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
orhttps
). 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 beforefolder_02
, andapage
comes beforeb_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.