TOC based on Markdown Headings (instead of nested nav structure)

[msmith-enea]

Hi there,

Assuming I've understood 2.7.0 changes correctly, it creates a neat TOC structure based on the navigation structure in the yaml file but it no longer uses markdown headings (like ##, ###, within a page as 1.1, 1.1.1, etc). If I've got this wrong, please correct me! Side point but related is I'm confused on how the demo print page is supposed to look (e.g. the 4. Demo Content has numbered headings underneath but this isn't shown on the TOC).

Unfortunately, this change directly conflicts with our usage, which is to convert the single site into a pdf book (much like word doc to pdf) output for customers (and, yes we would like to get away from this). We convert a mkdocs site into a pdf book based on a flat navigation structure (i.e. no nesting), and use the headings for the TOC depth (using some post-processing scripts/DOM manipulation to populate page numbers, etc). For us, this allows a predictable formatting and numbering (so e.g. ### heading is always 1.1.1 and always heading 3 font size), which each markdown file being a chapter/nav item in the book. We think the trade-off of not allowing nested structure and having a larger markdown file is best way of achieving this. However, with 2.7.2 we only see the very top level # heading in the TOC unlike 2.6.0.

Hope this explanation is clear but please ask clarification questions. I'm unclear whether the intention is to continue supporting our type of usage, whether it was overlooked and is intended to be supported, or if I've missed something obvious and my understanding is wrong.

Thanks,
Mark

[timvink]

The TOC structure has always been a bit confusing. The confusing bit is the concept of "sections". Every item in the toc will always be a top level heading of a page. It's more clear when you see the nav:

mkdocs-print-site-plugin/mkdocs.yml

Lines 31 to 43 in db297c9

	nav:
	- Home: index.md
	- Options: options.md
	- How to guides:
	- Export to PDF: how-to/export-PDF.md
	- Export to HTML: how-to/export-HTML.md
	- Add a print button: how-to/print_button.md
	- Add a PDF button: how-to/pdf_button.md
	- Add a cover page: how-to/cover_page.md
	- Add a banner: how-to/banner.md
	- Exclude content: how-to/do_not_print.md
	- Demo Content: demo_content.md
	- Contributing: contributing.md

So the how-to guides are all separate pages inside a section heading. They all start with a top level heading (#), but in the combined site, their level is idented because they are part of a section.

You mention you have your site navigation fully flat, with additional custom logic to generate a table of contents. I think you have two options: either start using sections headings in nav: and remove your additional custom logic, or just pin the version of this plugin. I'd recommend the latter.

For books, I'd recommend looking at more mature & specialized software like https://quarto.org/, which has a proven track recorded of published books.

[msmith-enea]

Thanks Tim, I'm little annoyed at myself for not coming across quarto before when evaluating options and will look at that separately.

Just to make sure we have the same understanding of the query here, I created an example to demonstrate 2.6.0 vs 2.7.2:

site_name: TOC Example
nav:
  - Chapter 1: chapter-1.md
  - Chapter 2: chapter-2.md
  - Chapter 3:
      - Sub Chapter A: chapter-3-a.md
      - Sub Chapter B: chapter-3-b.md
      - Sub Chapter C:
          - Sub Chapter I: chapter-3-c-i.md
          - Sub Chapter II: chapter-3-c-ii.md
          - Sub Chapter III: chapter-3-c-iii.md
  - Chapter 4: chapter-4.md
not_in_nav: |
    index.md
theme:
  name: material
  features:
    - navigation.expand
plugins:
  - search
  - print-site

Each chapter contains:

# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4

When viewing and print the site in 2.7.2:

Html 2.7.2

Print 2.7.2

Compared to 2.6.0:

Html 2.6.0

Print 2.6.0

Regardless of the approach taken by myself, I see challenge for anyone is how numbered headings work vs formatting of them which means a nested sub-sections aren't really workable either, e.g.

Print 2.7.2 - double page

Hopefully this better explains why I'm struggling to work out how this is supposed to work in practice. The 2.6.0 behaviour meant subsections were best avoided, the 2.7.0 behaviour makes subsections work great but as a consequence seems to have made headings unworkable.

My personal ideas essentially mean merging the headings and sub-section structure into a single navigation structure, e.g.

• Flattening the sub-sections and/or splitting them out into sub-divided print site page (or even multiple pages).
• Adjust the headings to match the depth on that flattened page, so they're continuously numbered and formatting aligns.

Given our appreciated usage of this plugin would be very willing to help with changes to support that if that aligns with the intentions.

For the moment, I will pin the version to 2.6.0 and then look at further steps.

[msmith-enea]

@timvink instead of leaving this open indefinitely, I intend to close this. Before I do that, I'm checking if there is response in the works or the follow up comment was missed.

Thanks

[msmith-enea]

Closing this now as per earlier comment. I do truly appreciate this is a freely available plugin and it has helped us.

My understanding is this is working as expected (i.e. it is an intentional breaking change from my perspective) and no further updates are planned or being considered (which if it was in scope, I would be happy to contribute towards this).

[bittorala]

This was indeed intended, it fixed #83, #111 and #123, and provided a predictable structure in the document as per the nav hierarchy. There were essentially two dimensions of depth to choose from: navigation hierarchy and headings. We chose to base the numbering on the first one, as it provided a more intuitive TOC and structure. However, the headings were also taken into account, which is why you see that 4.1.1 in your example. If the depth was configured to something bigger than 3, you should see the numbering in more headings too.

This topic is far from trivial, but I think the previous approach was more problematic. The roman and non-recursive numbering was confusing and had shortcomings for deep hierarchies. I would be open to discuss this in more length and potentially provide a config toggle to switch behaviours, but I am quite happy with the new approach.

[msmith-enea]

@bittorala thanks for following up, I'll think about a more concrete proposal. So you're aware, the subsection roman numeral numbering before was not used by ourselves and considering the subsections to be part of the consolidated navigation hierarchy makes perfect sense but I believe the side-effect that causes a breaking change for our usage is this has stopped the headings being part of the navigation hierarchy.

[bittorala]

Hi @msmith-enea. I see your problem. The change I did also used the sidebar's ToC as the main ToC in the printed page, to have a more predictable, easier-to-calculate and consistent index. However, I see that some people did want to have those headings included in the Table of Contents. We could include all the h>1 headings up to the level of toc_depth in the ToC (also considering the depth of the page in the nav hierarchy, as per my last comment), but I think for many users keeping the ToC at "page-level" is more intuitive, so maybe it should be made a config option.

I'd be happy to implement this if we agree on this approach.

[msmith-enea]

@bittorala to make sure we're on the same page, I can look at defining a test input and expected output, but happy to take your direction here. Controlling by config is fine with me as I think both approaches are valid and both have their positives and downsides.

[timvink]

Thanks for picking up the discussion @bittorala ! I'm open to solutions. Hopefully we can make this less confusing to users.

[bittorala]

@msmith-enea Yes, that would be quite helpful. Could you provide your expected output for the nested_sections test project, for instance? Another example more similar to your specific use case would also be quite useful. Thanks to both!

[msmith-enea]

@bittorala apologies, I've not got to this yet but will do