Allow numbering for only some pages / sections of a book

[choldgraf]

Currently, you can turn numbering on or off across sections of a MyST project. However, there are many cases where you only want a subset of the content numbered. This is most-common with books that have extra content as siblings rather than nested inside the book. For example, a site like this:

- Book (numbered)
  - Chapter 1
  - Chapter 2
- About (not numbered)
- Blog (not numbered) 
- Etc (not numbered)

In this case, authors should be able to specify a subset of the pages as numbered, and others as not numbered.

Related issues

This is similar to our issue around only showing pages under the current-active top level header in the sidebar, since that's also when you want to treat sections of content as independent of one another:

• Allow primary sidebar to only show pages from currently active section #2028

[brian-rose]

It's worth noting that this is something that is possible with sphinx-based JupyterBook: https://jupyterbook.org/en/stable/structure/configure.html#number-one-or-more-parts

[brian-rose]

Semantically, I find it useful to separate book contents into groups that are designed to be consumed in a specific order (numbering makes sense) and content that exists outside of that ordered list because the reader should be encouraged to jump in and out of it at any time (numbering doesn't help)

[FreekPols]

I got it sort of working in my book, though it took a while and needs some custom edits: https://freekpols.github.io/Mechanica/

[choldgraf]

Hacky solution: put sections in different folders and use a unified header in site configuration

I realized there's a simple-enough way to do this for my needs. It's something that I'm doing in the Jupyter Book 2 docs. Here's a summary:

1. Put your "book content" into a dedicated folder, or a dedicated repository, either will do.
2. Create a separate MyST configuration file for your site navbar (the thing at the top). Put only the configuration that you want shared across all top-level pages of your site. Put it in a source of truth repository (in our case, it's here: https://github.com/jupyter-book/jupyter-book/blob/next/docs/site.yml)
3. Treat each repository (or folder) as a separate MyST project. Each has their own myst.yml.
4. In each myst.yml, "extend" the site configuration you've created above. here's what it looks like in the source of truth, and here's what it looks like in one of the other folders or repositories.

Now, you can turn on numbering etc on a per-project basis, but your navigation bar will be the same across all of them.

If you're building all of this in a single repository, I think you'd need to ensure that the built assets get moved to different folders based on the top-level URLs you want, and you may also need to play with the BASE_URL. In our case, we're putting them in different repositories so we automatically get URLs.

Hope this is helpful!