Subpages

[fredrikekre]

It would be nice if Documenter's HTML renderer could support the following pattern:

page.md
   |------  subpage1.md
   |------  subpage2.md

where the subpages where displayed as H2-pages in the navigation bar.

After discussing with @mortenpi we have converged to the following suggestion:

Introduce a subpages function, very similar to hide which could be used in pages like:

pages = ["index.md", subpages("page.md", ["subpage1.md", "override heading" => "subpage2.md"])]

What would subpages do? The idea is that the only thing subpages does is that it changes the rendering of those pages in the navigation bar - from a H1 page to a H2 page.

Currently we always have the matching between a .md file and the .html file, and this will be preserved for subpages too, they will be their own .html pages.

Currently, by default, all html-pages are visible in the navigation bar (unless you use hide). The idea is that this should also be preserved, such that subpages are always visible in the navigation bar, even though they are on the H2 level.

We also think that it makes sense to leave the rendering of subpages alone (i.e. not change H1 to H2 for example). This hopefully makes implementation a bit simpler, since the only thing subpages will do is to change the navigation bar.

Some issues:

• How should we determine the name of a subpage? Currently Documenter looks for H1 headings to determine the name of the page. This will be done for subpages too, but since they are marked as subpages, it makes sense to also allow H2 heading as the highest level in the subpage. Probably we should first look for H1, and if none is found, look for H2. But should we do the same for non-subpages too? I'm guessing implementation is simplified a lot if we do they same lookup for normal pages too.

• If we are at a subpage, should H3 headings be shown in the navigation bar, the same way H2 headings are shown if we are on a normal page? Probably not, this just introduces a lot of clutter.

• If "page.md" in the example above have H2 headings, should they suddenly pop-up in the navigation bar when we are at page.md or should we consider the subpages to be the H2 headings for the main page? I think that it would be awkward if the H2-headings suddenly where spliced in between page.md and the subpages if we are at the page.md, but this can be worked around simply by not including any H2 headings on page.md if you don't want that behaviour. Let's just go with whatever makes implementing this simpler IMO.

Did I miss something @mortenpi ?

[mortenpi]

There were also two three additional small things that came up. Although they are orthogonal to the subpages idea, I'll just write them down here:

• Slightly change the style of non-link items in the navigation menu (e.g. "Manual" or "Library") to make it clear that they are not clickable.

• If Documenter can't figure out the name of a page for the navigation menu, it defaults to "-". This is not very helpful.. probably better to default to basename(source).

• We should Markdown.parse the page heading overrides in make.jl.

[LilithHafner]

Bump, I would like this feature to help with https://github.com/JuliaLang/julia/issues/52684

[kapple19]

Seconding this feature, All my collapse-ibles have a starting page labelled "Introduction" so there are "Introduction" pages everywhere. Need the conciseness of having the collapsible menu item also be a page to provide generic info about its sub-pages.