Native top navbar feature

[mortenpi]

There has been some discussion about introducing a proper top navigation bar to Documenter. The left sidebar can get quite busy and cluttered for big manuals, and it would be good to offer a way to offload some of that busyness to a different part of the UI¹. UI-wise, we're talking about something like MultiDocumenter adds:

Use cases

I do think there are few distinct use cases here we should consider when designing the UI/UX here:

1. Single package with large documentation

In this case you just want to be able to lift the top-level sections from the sidebar into the top bar (e.g. if you follow diataxis, you might have "Tutorials", "Guides", "Reference") in the top bar.

The API here could be pretty simple -- we keep using pages as is, and just with a switch to HTML, Documenter moves the top level sections from there into the top bar. When you navigate to a page under one of those top-level sections, the sidebar only shows the pages under that top-level section.

Example users: JuMP, Ferrite.jl, Julia's own manual²

2. Aggregation of small packages

This the the MultiDocumenter-workflow. You need a separate build step that pulls together all the different packages and then, during the aggregation phase, you add the top bar. The top-bar then offers navigation between the packages.

We should do this like MultiDocumenter does -- with HTML post-processing. Having the navbar natively in Documenter means that we have a way for the generating package to "hook into" Documenter's HTML DOM. Instead of having to hack the CSS, like MultiDocumenter does, we would just inject the correct HTML into the #documenter <div>. Basically, we can make the DOM structure of the top navbar public API.

Example users: JuliaLogging, JuliaDocs itself and many others orgs hosting closely related packages, Julia manual²

3. Combinations of the two

This is the hard case. Some ecosystems are made up of many packages, but some of the packages themselves are very extensive too (looking at you SciML). So you might want the multi-package thing, but also want extra navigation within a package.

A special case of this is probably where you have one big main package, but where you also want to link a few additional small extra packages (e.g. Makie, but you may also want to include something like GeoMakie.jl).

One option could be to just have different navbars for this. The in-page one could go just on top of the breadcrumb (or replace the breadcrumb altogether). But I feel that we'll end up with a lot of navigation bars then, which does not feel ideal either. Another issue is how to do two navbars responsively -- already managing the top bar and sidebar is a little tricky on mobile, so having to support yet another navigation menu is becoming messy.

Right now, my feeling is that we should stick to just one top bar, but offer a way to have package-specific links as well. Maybe some packages have a dropdown with their own in-site links when you are browsing that package? Essentially, the top bar could be slightly different depending on which page you are on. Implementation-wise, when you do the aggregate build, you don't just inject new DOM, but actually modify an existing set of top-bar links.

But this needs some thought in the context of an actual use case I think. And some mockups.

Example users: SciML, JuliaHub, Julia manual²

Implementation milestones

• Add the CSS/SCSS for styling the MultiDocumenter-like page-wide top bar. This can largely be stolen from MultiDocumenter, although I would like to re-do how it works on mobile. This requires some modification of the Documenter DOM.
• Add the option to generate single-package top-bars (i.e. case 1).
• Add official support for injecting the top bar into Documenter sites as a post-processing step. What MultiDocumenter does, but we could maintain it in DocumenterTools, as not to have too many separate packages around. It should also have the fallback generation for sites generated with older Documenter versions.
• Integrate the search -- there should be just one search UI.
• This is a bit aspirational, but we should also think about integrating cross-references within MultiDocumenter sites.

Footnotes

1. Separately, I think we also want to move to a right-hand sidebar for in-page headings (Add table of content for a specific page on the right side #1688, [review]: sub TOC on the right side of the page #1715). ↩

2. So, yes, I am listing the Julia manual under all the use cases. I think the Julia manual would benefit from the top bar. But there are a different ways of approaching this. We could just apply it to the current manual as it. But I also think we should consider actually hosting the standard library docs separately, and also bringing the ones that are currently completely separate "back into the fold" (Pkg in particular). Finally, the best way is probably to have some (possibly unversioned) top-level tutorial and guides sections, and then a Julia reference manual, and then the standard libraries, which corresponds to (3). ↩ ↩² ↩³

[mortenpi]

Here are a couple of design sketches.¹ I wanted to get a feel for what happens if we do have two top bars. First, two approximate ideas of how to implement a "in-site" top bar:

Option 1

Option 2

I kinda like Option 2, because that puts the top navigation on the "same level" as the sidebar. The rule would be that everything on white is part of this page and everything on the gray is part of the whole site. That's why the in-page navigation is also a part of the white part -- it's only relevant to the current page.

The only thing I am not a huge fan of is that the GitHub and other icons move very far to the right. We may want to limit their position. But I do think that's the right place for them (since they're also for the site, not the page).

We can then also add a cross-site MultiDocumenter-y top bar to both. Visually, we can make it a bit distinct from the other ones, indicating that this top bar is actually "higher level" than the rest of the navigation (cross-site, instead of in-site).

Edit: bringing the buttons closer to the middle:

Edit: and one more option where both top bars are just at the top, below each other.

Footnotes

1. There is also a live mockup, although it's not fully functional (e.g. light mode only): https://mortenpi.eu/mockups/2023-07-13-topbar-mock/ ↩

[mortenpi]

Two more mockups, with the full demo site here: https://mortenpi.eu/mockups/2023-07-14-topbar-mock/#debug:documenter-ext-navbar

[jvaverka]

First, thank you Morten for this write up.

Addressing multiple top bars

Right now, my feeling is that we should stick to just one top bar, but offer a way to have package-specific links as well. Maybe some packages have a dropdown with their own in-site links when you are browsing that package? Essentially, the top bar could be slightly different depending on which page you are on.

My initial reaction is that sticking to a single top bar is likely the best approach. Two top bars will most likely cause confusion no matter how well one is distinguished from another because readers are not accustomed to this hierarchy. We are witnessing this from new readers of current MultiDocumenter implementations which does a fair job distinguishing top and side bars.

Alternative approach to multiple top bars

Thinking about the three different use cases to consider:

1. Single package (with dense sections)
2. Aggregations (orgs or ecosystems)
3. Combinations of 1 & 2

Is there a consistent hierarchy that can provide natural navigation to all three? Consider the RSS reader, NewsFlash. Visually, the layout is described by the diagram.

 ┌──────────────────┬───────────────────┬──────────────────────┐
 │                  │                   │                      │
 │                  │                   │                      │
 │  subscriptions   │  article list     │  article content     │
 │                  │                   │                      │
 │                  │                   │                      │
 └──────────────────┴───────────────────┴──────────────────────┘

This feels like a more natural extension to how Julia docs have historically been structured.

┌───────────────────┬───────────────────┐
│                   │                   │
│                   │                   │
│  section pages    │  page content     │
│                   │                   │
│                   │                   │
└───────────────────┴───────────────────┘

Layout Adapted for Case 1

This use case seems to fit naturally to me. Adding the left "top-level sections" would be opt-in and not used for packages with smaller docs.

 ┌──────────────────┬───────────────────┬──────────────────────┐
 │                  │                   │                      │
 │   top-level      │                   │                      │
 │    sections      │   section pages   │    page content      │
 │                  │                   │                      │
 │                  │                   │                      │
 └──────────────────┴───────────────────┴──────────────────────┘

Layout Adapted for Case 2

This case basically represents what MultiDocumenter does but puts the packages to the left instead of on top.

 ┌──────────────────┬───────────────────┬──────────────────────┐
 │                  │                   │                      │
 │                  │                   │                      │
 │    packages      │   sections        │       page           │
 │                  │                   │                      │
 │                  │                   │                      │
 └──────────────────┴───────────────────┴──────────────────────┘

Layout Adapted for Case 3

This case is of course trickier, but maybe any shortcomings can be addressed with other enhancements to Documenter. For instance, let's say that if #701 is complete then the middle "sections" can provide access to a tree of pages rather than a list. In any case, the general layout would be the same as for Case 2.

Nice side effects

Search

There is one search for every article (or page). See screen recording for NewsFlash example.

Screencast.from.10-25-2023.12.31.48.PM.webm

Responsiveness

This layout may also benefit mobile renders as well if we could achieve the same responsive behavior shown by NewsFlash.

Screencast.from.10-25-2023.12.26.11.PM.webm

(Sorry my mouse does not show up in the recording, but the left-next bar is accessed by clicking the top-left icon)

[mortenpi]

I do intend to have a separate sidebar for the in-page headings. So if we'd make the top-level links a sidebar too, then we'd have four columns, which might be a bit much?

One site that I've used as inspiration is learn.microsoft.com, which loves top bars: https://learn.microsoft.com/en-nz/dotnet/standard/base-types/regular-expressions

But maybe cc @pfitzseb @ChrisRackauckas and @Dattax as to what your thoughts are on having this as an extra sidebar, rather than as a top bar.

One thing to note that is we wouldn't be fully married to the layout choice -- I assume that we'd be populating the two navigations the same way, so changing the layout or adding an option for the second one wouldn't be too problematic.

[Dattax]

It would be nice have all 4 (main top bar, additional top bar, right-side menu, left-side menu), but maybe there is a way to have an option of whether you want the additional top bar there or not? (might be worth saying the same about the right-side menu).

[jvaverka]

I do intend to have a separate sidebar for the in-page headings. So if we'd make the top-level links a sidebar too, then we'd have four columns, which might be a bit much?

Yeah, that sounds busy. Another option would be to use a small floating table of contents in the left-hand margin. Although this may not help much and some readers may prefer to hide the section list.

[ChrisRackauckas]

this one looks nice. Though we'd want the top one to be the multidocumenter one.

[mortenpi]

this one looks nice. Though we'd want the top one to be the multidocumenter one.

That's the one I'm aiming for right now as well. And yea, the blue one is representing the MultiDocumenter top bar.

[mortenpi]

Another option would be to use a small floating table of contents in the left-hand margin.

@jvaverka Is there example somewhere of what you have in mind?

[jvaverka]

Sorry, I meant right-hand - as seen in the image above.

And regarding hiding page contents: see reader mode of Quarto for example. R for Data Science uses this feature and allows readers to hide navigation sections to focus on the content. I consider this nice to have but useful when things get busy.

[mtiller-jh]

FYI, I recent did a Julia project using retype and a big part of the reason was the right side bar. You can see the site here. Generally, I really like all the navigation features in retype.

https://juliacomputing.github.io/modeling-toolkit-introduction/

You'll notice that they have space for a series of links (you provide the links, they are not part of the documentation in this case). The only link I included was a link back to the MTK reference documentation.

[mtiller-jh]

One thing to note about the sidebars here is that they are only as large as they need to be. That is also a nice feature.

[lazarusA]

@mtiller-jh how did you include plots and code? are you using this in combination with Documenter 1.0? and if so, do you have a link to Documenter writer used? The site looks nice, but I didn't find any source code :(

[mtiller-jh]

@lazarusA I use my Runlit package which, in turn, relies on the jlrun utility. The net effect is that I run Literate.jl over my Julia scripts to produce really nice Markdown and associated images which are then picked up by any static site generator I want and processed into a static site. I've had excellent results both with retype for web sites and sli.dev for presentations.

Yes, it is true that retype doesn't come with source code, but sli.dev does and so do dozens (if not hundreds) of other static site generators. This pipeline works with any static site generator that accepts Markdown as input.

[shravanngoswamii]

We have just redesigned Turing.jl's website and merged it into Quarto, and now we want a native top bar for all Turing satellite projects which are using Documenter.jl. Currently, Multidocumenter is being used to add all packages under single navigation and search, but we are looking for a way to do it to individual package's doc itself! Let me know if I can help add this feature.

cc @mortenpi

[Datseris]

this one looks nice. Though we'd want the top one to be the multidocumenter one.

That's the one I'm aiming for right now as well. And yea, the blue one is representing the MultiDocumenter top bar.

@mortenpi I am confused. There are two top bars, but the lower top bar seems not necessary? Is it a selection of topics that already exist in the left side bar? If yes, why duplicate?

This overall looks great but I am confused about hte presence of two top bars and I cannot tell at a glance what they mean. And that is exactly the purpose of the sidebar or top bar: that you can tell within a second exactly what this content is.

[mortenpi]

There are two top bars, but the lower top bar seems not necessary? Is it a selection of topics that already exist in the left side bar? If yes, why duplicate?

No duplication. The idea I had was that the top-level elements from the sidebar move to the top bar if you enable it, and the sidebar only shows the subitems of the currently active top-level item. In other words, different pages can have different sidebars.

This overall looks great but I am confused about hte presence of two top bars and I cannot tell at a glance what they mean.

The upper top-bar is MultiDocumenter, and goes across packages. The lower one is within a package. Ultimately, it's going to be up to the user if they want that or not -- I expect the lower, Documenter top-bar to be opt-in, so you can just not have it for your packages, if you know you're aggregating them with MultiDocumenter.