Towards a more flexible pages interface

[asinghvi17]

In makedocs, the way to specify pages is currently pretty rigid - you can only pass in a very rigid nested array of strings (and indicate title / page path).

I, and many others, would like to have a more flexible way to define pages for the sidebar, so that we can e.g. define a section header that is also a page / clickable, and has sub-pages associated with it. This is already possible in DocumenterVitepress although you have to define the sidebar manually in the config.mts. The basic DimensionalData docs is a good example - the "Getting started" is a page, but is also the section header for that section of the docs. There are also subsidiary pages.

Another example is choosing which subsections of the sidebar to expand on a more granular level. At the moment, we only have the ability to set a global threshold for the nesting level at which things collapse. But I may want a top level section to be collapsed by default, and a lower level section to not be collapsed.

There is some current functionality that is slightly similar, and that's hide - which takes any pages-compatible structure / type, and returns a 4-tuple of (hidden::Bool, title::String, path::String, children::Vector) (I think). So my first thought is that we should make this a struct that people can instantiate, and include some more metadata. A basic prototype might be (borrowing from Documenter.NavNode):

struct PageNode
    # page contents
    page::Union{String, Nothing}
    children::Vector{PageNode}
    # metadata
    title_override::Union{String, Nothing}
    visible::Union{Bool, Nothing}
    collapsed::Union{Bool, Nothing} # nothing here indicates that we follow the global spec
end

Constructor

PageNode(input::Pair; kw...) = PageNode(input[1], input[2]; kw...)
PageNode(input::String; visible = nothing, collapsed = nothing) = PageNode(input, PageNode[], nothing, visible, collapsed)

function PageNode(input::Vector; kw...)

	children = PageNode.(input; kw...)

	return PageNode(nothing, children, nothing, visible, collapsed)

end

function PageNode(titlechildren::Pair{String, Vector}; kw...)

	children = PageNode.(titlechildren[2]; kw...)

	return PageNode(nothing, children, titlechildren[1], visible, collapsed)
end

function PageNode(original_page, children::Vector; kw...)
	pn1 = PageNode(original_page; kw...)

	@assert isempty(pn1.children) "You can't specify multiple children!  Look at the type of the first argument to this function."

	return PageNode(pn1.page, PageNode.(children; kw...), pn1.title_override, pn1.visible, pn1.collapsed)
end

and then we can recursively parse all input to pages into PageNodes.

@mortenpi mentioned that we could initially disallow collapsing pagenodes that have a non-nothing page but non-empty children, pending a section collapser element in the UI.

The main parser is in walk_navpages so that's where we have to inject the override.

Documenter.jl/src/builder_pipeline.jl

Line 181 in 6abd828

function walk_navpages(visible, title, src, children, parent, doc)

cc: @mortenpi @fredrikekre

[odow]

x-ref #344

[asinghvi17]

Thanks! That seems to be incompatible with the current NavNode structure, see here:

Documenter.jl/src/documents.jl

Lines 236 to 241 in 6abd828

	mutable struct NavNode
	"""
	`nothing` if the `NavNode` is a non-page node of the navigation tree, otherwise
	the string should be a valid key in `doc.blueprint.pages`
	"""
	page::Union{String, Nothing}

but I'm sure that with some effort we could fix that...

[odow]

Yeah if you're thinking about making it more flexible, this is something that people keep asking for.

[fredrikekre]

See also #701.

[asinghvi17]

Initial prototype up and running (pages but no external links or collapsing spec yet) - it just worked!!

https://github.com/asinghvi17/DocumenterPages.jl

[asinghvi17]

Documenter.jl/src/html/HTMLWriter.jl

Line 1237 in 6abd828

item = if length(nctx.idstack) >= ctx.settings.collapselevel && children.name !== DOM.TEXT

is where the collapsing logic goes