Alternative table of contents for PDF builds

[effigies]

Context

I work on some fairly technical documents, where we basically have two modes of writing: 1) Reference and explanation; 2) Some technical hand-holding for new users.

For example, if I want to specify a JSON schema, the main document includes the specific fields, types, values and constraints, as well as high-level overviews (why is it structured this way, how to think about this to help you write these documents or tooling around these documents).

For newer users who want to use the tooling, something like a JSON 101 that's customized to the application at hand can be useful. These can get large and potentially sprawl away from the core topic, which is fine because they're packed away in a separate HTML page where they can be ignored by a focused search.

However, including these in a PDF would make it excessively large and harder to use as an archival reference, which seems to me the main reason for PDF builds in my use case. It could also be useful to use an alternative section ordering for PDF and HTML.

Proposal

I would like to have some way of specifying a different TOC for different builders.

Options I've thought of (using latex as example, but could apply to other builders):

• _toc.yml as default, _toc.latex.yml as override
• TOC configurable in _config.yml, and overridable in a latex: section
• An exclude: latex option for pages in _toc.yml

Tasks and updates

No response

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[mmcky]

Thanks @effigies these are all interesting ideas.

while there is no automatic way to do what you're thinking, you could specify --toc and --config as part of your build command using the jupyter-book cli which might get you closer to what you want in terms of behaviour.

jb build --toc=_toc_latex.yml --config=_config_latex.yml

https://jupyterbook.org/en/stable/reference/cli.html#jupyter-book-build