## Configure a single top-level set of chapters/sections
If you're only using a single list of chapters, and not organizing them into parts, you can configure each with the `options:` key.
If you're only using a single list of chapters, and not organizing them into parts, you can configure the single group of chapters with the `options:` key.
For example:
...
...
@@ -36,9 +36,14 @@ chapters:
-file:path/to/part1/chapter2
```
## Configure an individual Part
:::{note}
If you're using `parts`, then the `options:` key has no effect.
You should configure each part individually (see below).
:::
## Configure one or more Parts
If you are organizing your book into **parts** (groups of chapters), you can configure each set of chapters separately by providing `key: value` pairs alongside each `part` entry, like so:
If you are organizing your book into **parts** (groups of chapters), configure each part by providing `key: value` pairs alongside each `part` entry, like so:
```yaml
format:jb-book
...
...
@@ -55,8 +60,8 @@ parts:
-file:path/to/part2/chapter2
```
In this case, the `numbered:`option would *only apply to Part 1*, and not Part 2. If you would like numbering across your
project you will need to add `numbered: true` to all `parts`.
In this case, the `numbered:`*only applues to Part 1*, and not Part 2.
If you want all parts to be numbered, you will need to add `numbered: true` to all `parts` entries.
:::{warning}
Currently there is no global setting to enable `numbered: true` across all parts.
...
...
@@ -68,8 +73,8 @@ defaults:
numbered:true
```
as sphinx will issue warnings due to `numbered` flag being set for substrees. It also causes unexpected
output.
as sphinx will issue warnings due to `numbered` flag being set for subtrees.
It also causes unexpected output.
:::
...
...
@@ -100,8 +105,12 @@ in the table of contents, it does not change the actual chapter/section title.
(toc/numbering)=
## Number your chapters and sections
You can automatically add numbers to each chapter of your book.
To add numbers to **all chapters of your book**, add the `numbered: true` flag to your book's defaults, like so:
You can automatically add numbers chapters of your book.
Numbers will follow a hierarchy according to the structure defined in your `_toc.yml` file.
### Number a single group of chapters
If using a single set of chapters for your book (aka, no Parts), add numbers to them with the `numbered: true` flag, like so:
```yaml
format:jb-book
...
...
@@ -113,50 +122,58 @@ chapters:
-file:chapter2
```
Numbers will follow a hierarchy according to the structure defined in your `_toc.yml` file.
### Number one or more parts
```{margin}
Continuous numbering is now the default behavior from `jupyter-book>=0.11.2`
```
By default, chapter numbering will be continuous between parts (i.e. they will not re-start each section at `1.` each time)
using an extension called [sphinx-multitoc-numbering](https://github.com/executablebooks/sphinx-multitoc-numbering).
:::{tip}
To **restart chapter numbering between parts**, use the following setting in your `_config.yml` file:
If using one or more parts, add the `numbered: true` option to each.
For example, to number all parts in a two-part book:
```yaml
html:
use_multitoc_numbering:false
format:jb-book
root:intro
parts:
-caption:Part 1
numbered:true
chapters:
-file:part1/chapter1
-caption:Part 2
numbered:true
chapters:
-file:part2/chapter1
```
This was the **default behaviour** prior to `jupyter-book<0.11.2`.
:::
:::{admonition} Limit the depth of numbering
If you'd like to limit the depth of numbering, use an **integer** for the `numbered` flag.
This will be the depth of sub-sections to continue numbering.
For example, `numbered: 3`.
:::
If you'd like to number **subsets of chapters**, group them into parts and
apply the `numbered: true` flag to the parts whose chapters you wish to be numbered.
For example:
To number only the second part of a book:
```yaml
format:jb-book
root:intro
parts:
-caption:Part 1
numbered:true# Only part 1 will be numbered
chapters:
-file:part1/chapter1
-caption:Part 2
numbered:true# Only the second part is numbered
chapters:
-file:part2/chapter1
```
#### Restart numbering between parts
By default, chapter numbering will be continuous between parts (i.e. they will not re-start each section at `1.` each time)
using an extension called [sphinx-multitoc-numbering](https://github.com/executablebooks/sphinx-multitoc-numbering).
To **restart chapter numbering between parts**, use the following setting in your `_config.yml` file:
```yaml
html:
use_multitoc_numbering:false
```
### Limit the depth of numbering
If you'd like to limit the depth of numbering, use an **integer** for the `numbered` flag.
This will be the depth of sub-sections to continue numbering.
For example, `numbered: 3`.
::::{admonition} A few caveats about numbering
Jupyter Book relies on {term}`Sphinx` to apply section numbering, and this has a
