Headings are hard to discern

[mid-kid]

I'm finding it hard to tell whenever I'm moving into a new section, both because the difference in size between them isn't very clear, and because the different types of headings seem to be used inconsistently. This makes it hard for me to skim the document and find the right section.

[ISSOtm]

The heading consistency is something that we inherited from the OG document, I believe.

As for improving the feeling of switching sections, horizontal bars and/or a different background per heading (akin to the style used by nocash's docs) would probably help a lot.

[avivace]

Yes, the problem in headings and subheadings is that they were used consistently in the wiki and the export added another layer of confusion, so you may see a register in h2 in one page and one in h4 in another.

[avivace]

f17d85b

[mid-kid]

This seems to break under firefox ESR 68.4.2

Dunno about newer firefox versions.

EDIT: No longer an issue, firefox ESR is now on 78.

[nitro2k01]

Imo, the current tentative fix is kind of a mess. One issue compared to the original version of Pan Docs, is that the original version has a ToC and sub-ToCs whereas we currently only have a single level of ToC. All sections linked from a ToC (whether from the main or a sub-ToC) are highlighted with the grey background.

My suggestions are:

1. Recreate the multi-level ToC from nocash's Pandocs. (Whether that ends up being a tree structure at the top, local ToC's in each section that needs one, or both.)
2. Like nocash's version, highlight all main headings in some way. Unlike nocash's version, probably highlight subsections differently, for example with a lighter background.

[ISSOtm]

Can you check if this preview of #292 fixes this issue?

[mid-kid]

That sidesteps the issue by just putting everything on a separate page, and having no way to view everything as a single page, so I'm not sure how it'd look like that. If the intention is to keep it all on separate pages I'd say it's solved, since this works even when printed to PDF (every section has a pagebreak), though the horizontal gray bars in for example 3.3 OAM and 3.7 Palettes look out of place.

[ISSOtm]

As far as I remember, the push for a single-page document was the ability to easily search it via Ctrl+F, but mdBook provides this functionality via the search bar. Were there any other reasons?
As a fallback, the print page is a single page, if absolutely required.

I added these gray bars manually to separate first-level sections, since there is next to no margin above h1s. Maybe they should be moved to sub-pages, or changed to second-level sections instead?

[mid-kid]

I'm not seeing a search bar?

As for the gray bars, either solution sounds fine, just don't have multiple h1s in one page I guess.

[avivace]

As far as I remember, the push for a single-page document was the ability to easily search it via Ctrl+F, but mdBook provides this functionality via the search bar. Were there any other reasons?
As a fallback, the print page is a single page, if absolutely required.

I added these gray bars manually to separate first-level sections, since there is next to no margin above h1s. Maybe they should be moved to sub-pages, or changed to second-level sections instead?

The single page version is here to stay, not only for the CTRL+F but also to stay consistent to the document spirit. It's not a big deal and in the meantime we can also keep the old vuepress version as the one-page version

[ISSOtm]

Does the print page fulfill that requirement?

I'm not seeing a search bar?

I removed the search feature by accident while trying to speed up CI, my bad :P It's back, though.

[mid-kid]

I have no idea why, but that search button wasn't appearing for me before.

[ISSOtm]

It's because I had disabled the search feature by mistake while trying to speed up CI ^^'

[ISSOtm]

Closed by #292