Enumerate headings using the nav structure

[SimonDFischer]

Your plugin is helpful and works fine, thanks for that!

There is one point I would like to suggest for enhancement (e.g. as an option to the existing method). I understand that your enumeration of headings is only based on the level of the markdown header, and ignores the nav structure from mkdocs.yml. In addition, your TOC has some visual-only features to reflect this nav structure (like the "Customization" title in https://timvink.github.io/mkdocs-print-site-plugin/print_page.html).

It would be more natural to me to consider the nav structure (and adjust the level of the header). For example, your "Customization" would create a # Customization (i.e. Section 3), and the subjacent pages would be included like ## Adding a print button (i.e. Section 3.1) or ## Adding a PDF button (i.e. Section 3.2).

[timvink]

Thanks for the feedback!

I see your point about including the navigational section headers in the enumeration. Basically you're proposing:

1) To insert a heading into the print page for each section 2) To update the enumeration as if the section is a chapter

In terms of implementation, 1) is relatively easy to do but 2) is more involved. If you treat a section as a chapter, should heading 1 on a page then become heading 2? What about pages (chapters) that start before a section (like 'Home' and 'Options' in our example). Should they have an enumeration of 0.1 and 0.2 ? Basically, I'm not convinced (yet) this would be a good / clean solution.

I had a look at how LateX does it (which is more commonly used for technical reports like papers and books). Mkdocs sections would be analogous to latex 'parts'. Those parts are enumerated separately with roman numbers (source):

I think adding roman enumeration to mkdocs sections and inserting a full page 'section title' for each section could be a nice solution. Any thoughts? Would that fit your use case?

[SimonDFischer]

Your comparison with LaTeX is good. The \part element in LaTeX somehow compares with our nav section element in mkdocs (in this case, enumeration should just re-start after a new \part).

However, I think this is only a valid comparison if nav has a depth of 2. With a nav of depth 3 or more, this concept breaks (e.g. Customization > Details > index.md). BTW, your print site produces a TOC with the same formatting for all nav section levels.

I think a general solution would be to build up the heading levels according to the nav section structure, and then shift all headings of a page accordingly.

In your example:

# Home
# Options
# Customization
## Adding a print button
### Adding a print button to mkdocs-material theme
### Adding a print button to mkdocs theme
## Adding a PDF button
### ...
...
# Demo content
...

It is then only a matter of choice if headings of level 1 should be presented like a \part (with separate page), or like a \section.

[timvink]

With a nav of depth 3 or more, this concept breaks

Good point, that's an edge case. When enumerating sections ('parts') separately, a tree like 'Customization > Details > index.md' would have 'Customization' be enumerated as I, and 'Details' as I.I (roman enumeration). I don't see nav's with a depth of 3 or more often.

I think a general solution would be to build up the heading levels according to the nav section structure, and then shift all headings of a page accordingly.

That would be complex to build, but more importantly it is confusing for users. It will mean heading levels will be different on the print page compared to on the actual site page. And there are edge cases to deal with as well, f.e. headings are limited to heading 6 depth, and if you have a navigation of depth 3 you would end up with headings with depth 9.

Adding roman enumeration to mkdocs sections (nested or not) and inserting a full page 'section title' for each section seems a consistent and elegant solution to me. I'll implement it next time I work on this plugin.

[SimonDFischer]

We try to limit our sections of a technical specifcation to a depth of 3, and with additional 2-3 levels on a single page, the total depth is indeed a bit high. Looking forward to your proposal.

[timvink]

Allright, I have something working :)

Here is a table of contents with pages that are nested in sections 3 deep:

The print page now also shows the sections (in print mode they show as a full page).

If you want to try it out already, you can get the development version like so:

pip uninstall mkdocs-print-site-plugin
git clone git@github.com:timvink/mkdocs-print-site-plugin.git
cd mkdocs-print-site-plugin
pip install .

[timvink]

Released in v1.0. Let me know if you have any feedback!

[SimonDFischer]

I like your implementation and it seems to work fine in our case, thank you Tim. Only one remark so far: The list item (dot) before roman subsections (I.I and I.I.I in your above example) should be removed in my opinion.

[timvink]

Good to hear!

What would you recommend as an alternative for the dots between roman numbering of subsections? Let's say the second section has three subsections. Would you prefer II III over II.III ?

[SimonDFischer]

The variant like I.I is fine for me. My issue are the big list points before the roman numbers, as shown below. I think they are not needed. In addition, indentation of a roman subsection should be less or equal than the arabic subsections of this level.