Ctrl+K

Migrate your old Table of Contents to the new TOC structure

Migrate your old Table of Contents to the new TOC structure#

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).

This is a short guide to explain the differences between the old and new Table of Contents structures, to help you update them.

See also

If you’d like to automatically convert your Table of Contents, you may also try running the following command:

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.

Step 0: Starting with an old Table of Contents structure#

Let’s say you’re starting with this Table of Contents structure:

- 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.

🚀 RELEASE: Jupyter Book v0.11.1   Jupyter Book and MyST at AGU 2021
Contents