## Contents

In Jupyter Book v0.11, we introduced a new Table of Contents structure. The new structure is a bit more rigid and explicit, which should allow for a cleaner mapping of TOC structures onto book structures. It also introduces the concept of TOC formats, which allows you to specify different kinds of documents in the TOC (to start with, Books and Articles).

jupyter-book toc migrate path/to/_toc.yml


This will automatically generate a new TOC, though it will remove comments and may slightly alter formatting.

- file: intro
numbered: true
- part: Get started
chapters:
- file: start/overview
- file: start/build
- file: start/publish
sections:
- file: publish/gh-pages
- file: publish/netlify


This structure defines a landing page from the file intro, as well as a single part with a few chapters inside.

Next we’ll convert this to the new TOC format.

## Step 1: define a “root” page¶

The new TOC format requires an explicit page to be set as your document’s “root”. This is the first page that users see when they navigate your book or article. To add one, we’ll explicitly define our intro page as the root document and move it to the root of the YAML file.

root: intro
numbered: true
- part: Get started
chapters:
- file: start/overview
- file: start/build
- file: start/publish
sections:
- file: publish/gh-pages
- file: publish/netlify


## Step 2: Add a “format” key¶

The new TOC structure asks you to explicitly define a format for the Table of Contents. This helps Jupyter Book know what kind of document you are building. You currently have two options:

• format: jb-book for multi-page books

• format: jb-article for articles made up of sections

Different kinds of documents have different TOC key names. For example, Books map on to “parts” and “chapters” at a top level, and “sections” underneath each chapter. Articles may have collections of “sections”, but no “parts” and “chapters”.

In this case, we have “parts” defined, so we’ll choose the jb-book format.

root: intro
format: jb-book
numbered: true
- part: Get started
chapters:
- file: start/overview
- file: start/build
- file: start/publish
sections:
- file: publish/gh-pages
- file: publish/netlify


## Step 3: Explicitly define the parts¶

The collection of “parts” now exists underneath a parts key. The value of parts is a list where each item corresponds to one part. We now use the caption key to define the title of each part.

root: intro
format: jb-book
numbered: true
parts:
- caption: Get started
chapters:
- file: start/overview
- file: start/build
- file: start/publish
sections:
- file: publish/gh-pages
- file: publish/netlify


An alternative structure for single-part books

If your book only consists of a single part, you could directly add the chapters key to the root of your TOC, like so:

root: intro
format: jb-book
numbered: true
chapters:
- file: start/overview
- file: start/build
- file: start/publish
sections:
- file: publish/gh-pages
- file: publish/netlify


## Step 4: Move the configuration¶

The new TOC structure has a more explicit configuration structure, and has different locations for global configuration and section configurations.

Because we wish for all sections to be numbered, we will keep numbered: true, but must move it to a defaults key, which makes it a default for all pages in the TOC.

root: intro
format: jb-book
defaults:
numbered: true
parts:
- caption: Get started
chapters:
- file: start/overview
- file: start/build
- file: start/publish
sections:
- file: publish/gh-pages
- file: publish/netlify


## Step 5: We’re done!¶

This TOC structure is now compatible with the new Jupyter Book TOC style. We have taken a minimal set of steps here to convert over the old TOC structure, but if you’d like to learn more about the Table of Contents, check out How headers and sections map onto to book structure.