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

```{post} 2021-06-17
:author: EBP
:image: 1
:excerpt: 2
```

In Jupyter Book v0.11, we [introduced a new Table of Contents](https://jupyterbook.org/reference/_changelog.html#v0-11-0) 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.

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

```bash
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:

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

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

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

```yaml
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
```

:::{admonition} 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:

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


```yaml
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 {ref}`jb:toc/structure`.