top_menu: address review of #2904

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* Added a `top_menu` option to `Documenter.HTML` for multi-section documentation with a top navigation bar. With `HTML(top_menu = true)`, each top-level entry of `pages` becomes a section in the top bar, with its own sidebar navigation tree and previous/next page links. ([#2904])
 * The HTML output now sets a `no-referrer` referrer policy by default, so that the CDNs serving the fonts, stylesheets and scripts are no longer told which page the reader is on. It can be changed or disabled with the `referrerpolicy` keyword of `Documenter.HTML`. ([#2391], [#2401])
 
 ### Fixed
@@ -54,7 +55,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-* Added `top_menu` keyword argument to `makedocs` for multi-section documentation with a top navigation bar. This enables upper-level organization above the sidebar, with each section maintaining its own sidebar navigation tree. ([#2866])
 * The version selector now also preserves the anchor (hash) when switching between documentation versions. Additionally, the outdated/dev version warning banner now also tries to keep you on the same page (and position) when linking to the latest stable release. ([#2880])
 * Added `Remotes.Forgejo` for specifying a `Remote` hosted on a Forgejo instance (such as codeberg.org). ([#2857])
 * Doctests now default to the `parser_for_module` of the module that the docstring appears in, allowing modules that set their syntax version via `Base.Experimental.@set_syntax_version` to have their doctests parsed with the correct syntax automatically. Also added support for `DocTestSyntax` metadata and per-block `syntax=` attributes to explicitly specify a syntax version. ([#2874])
@@ -2324,6 +2324,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2880]: https://github.com/JuliaDocs/Documenter.jl/issues/2880
 [#2889]: https://github.com/JuliaDocs/Documenter.jl/issues/2889
 [#2894]: https://github.com/JuliaDocs/Documenter.jl/issues/2894
+[#2904]: https://github.com/JuliaDocs/Documenter.jl/issues/2904
 [#2905]: https://github.com/JuliaDocs/Documenter.jl/issues/2905
 [#2912]: https://github.com/JuliaDocs/Documenter.jl/issues/2912
 [#2925]: https://github.com/JuliaDocs/Documenter.jl/issues/2925

assets/html/js/sidebar.js

@@ -62,7 +62,7 @@ $(document).ready(function () {
   // causing the header to be hidden under the fixed top menu.
   if (location.hash) {
     var target = document.getElementById(
-      decodeURIComponent(location.hash.substring(1))
+      decodeURIComponent(location.hash.substring(1)),
     );
     if (target) target.scrollIntoView();
   }

assets/html/scss/documenter/layout/_topmenu.scss

@@ -82,10 +82,19 @@ $documenter-topmenu-active-color: $documenter-sidebar-menu-active-color !default
     }
 
     .docs-top-dropdown-caret {
-      margin-left: 0.35em;
-      font-size: 0.75em;
+      display: inline-block;
+      font-style: normal;
+      font-variant: normal;
+      text-rendering: auto;
+      margin-left: 0.5em;
+      font-size: 0.65em;
       opacity: 0.6;
       line-height: 1;
+      &::before {
+        @include font-awesome;
+        // fa-chevron-down
+        content: "\f078";
+      }
     }
   }
 

docs/Project.toml

@@ -2,8 +2,7 @@
 Changelog = "5217a498-cd5d-4ec6-b8c2-9b85a09b6e3e"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
-LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"
 
 [sources]
-Documenter = {path = ".."}
+Documenter = { path = ".." }

docs/src/man/guide.md

@@ -448,14 +448,12 @@ from the sidebar with the help of the [`hide`](@ref) function.
 
 ## Top Menu for Multi-Section Documentation
 
-For larger documentation projects, you can create a top-level navigation bar using the
-`top_menu` boolean argument to [`makedocs`](@ref). This allows you to organize your documentation
-into multiple distinct sections, each with its own sidebar navigation.
+For larger documentation projects, you can create a top-level navigation bar by passing `top_menu = true` to [`Documenter.HTML`](@ref). This allows you to organize your documentation into multiple distinct sections, each with its own sidebar navigation.
 
 ```julia
 makedocs(
     ...,
-    top_menu = true,
+    format = Documenter.HTML(top_menu = true),
     pages = [
         "Getting Started" => [
             "Home" => "index.md",
@@ -478,31 +476,26 @@ makedocs(
 )
 ```
 
-When `top_menu = true`, the first layer of the `pages` argument is used as the top menu
-(each entry becomes a section). The `pages` section is still interpreted for sidebar
-navigation within each section.
+With `top_menu = true`, the first layer of the `pages` argument is used as the top menu (each entry becomes a section), and the rest of `pages` is interpreted as usual for the sidebar navigation within each section:
 
-- A horizontal navigation bar appears at the top of the page with the section titles
-- Each section has its own sidebar navigation showing only the pages in that section
-- Clicking a section title navigates to the first page of that section
-- The sidebar's previous/next navigation stays within each section
+  * a horizontal navigation bar appears at the top of the page with the section titles, and hovering over a section title shows a dropdown with the top-level entries of that section;
+  * each section has its own sidebar navigation showing only the pages in that section;
+  * clicking a section title navigates to the first page of that section;
+  * the previous/next page links at the bottom of each page stay within its section;
+  * a section hidden with [`hide`](@ref) is not shown in the top menu, and neither are hidden entries in the dropdowns.
 
-Each entry in the first layer of `pages` must be a `"Section Title" => pages_array` pair,
-where `pages_array` follows the same format as the `pages` argument (supporting nested
-subsections, page titles, etc.).
+Each entry in the first layer of `pages` must be a `"Section Title" => pages_array` pair, where `pages_array` follows the same format as the `pages` argument (supporting nested subsections, page titles, etc.). A `"Section Title" => "page.md"` pair creates a section with a single page. Entries without a title, such as a bare `"page.md"`, are an error.
 
 !!! note "Landing page"
-    The section containing `index.md` will be displayed first when the documentation is
-    opened, since `index.md` becomes the landing page. Make sure to place your main entry
-    point in the appropriate section.
+    As usual, `index.md` becomes the landing page, so the section containing it will be displayed first when the documentation is opened. Make sure to place your main entry point in the appropriate section.
 
 !!! warning "Unique pages across sections"
-    Each page should appear in only one section. Having the same page in multiple sections
-    will cause navigation issues, as a single page can only belong to one section's
-    navigation tree.
+    Each page should appear in only one section. Having the same page in multiple sections will cause navigation issues, as a single page can only belong to one section's navigation tree. Documenter warns if it detects this.
 
-If `top_menu = false` (the default), Documenter uses the standard single-sidebar
-behavior controlled by the `pages` argument.
+!!! note "Small screens and other output formats"
+    On touch and small-screen devices, the dropdowns are not shown, and a section is reached through its title, which links to its first page. The `top_menu` option only affects the HTML output: other writers, such as the LaTeX/PDF one, ignore it and render `pages` as a regular hierarchy of sections.
+
+If `top_menu = false` (the default), Documenter uses the standard single-sidebar behavior controlled by the `pages` argument.
 
 
 ## Adding a logo or icon

src/builder_pipeline.jl

@@ -177,7 +177,6 @@ generating [`NavNode`](@ref)s and related data structures in the
 process.
 
 This implementation is the de facto specification for the `.user.pages` field.
-
 """
 function walk_navpages(visible, title, src, children, parent, doc)
     # parent can also be nothing (for top-level elements)
@@ -187,9 +186,7 @@ function walk_navpages(visible, title, src, children, parent, doc)
         src in keys(doc.blueprint.pages) || error("'$src' is not an existing page!")
     end
     nn = Documenter.NavNode(src, title, parent)
-    if src !== nothing
-        push!(doc.internal.navlist, nn)
-    end
+    (src === nothing) || push!(doc.internal.navlist, nn)
     nn.visible = parent_visible && visible
     nn.children = walk_navpages(children, nn, doc)
     return nn

src/documents.jl

@@ -284,8 +284,6 @@ mutable struct NavNode
     next::Union{NavNode, Nothing}
 end
 NavNode(page, title_override, parent) = NavNode(page, title_override, parent, [], true, nothing, nothing)
-
-
 # This method ensures that we do not print the whole navtree in case we ever happen to print
 # a NavNode in some debug output somewhere.
 function Base.show(io::IO, n::NavNode)
@@ -528,7 +526,7 @@ function Document(;
         Dict{Markdown.Link, String}(),
         Set{Symbol}(),
         Dict{String, String}(),
-        Dict{String, Tuple{String, String}}(),
+        Dict{String, Tuple{String, String}}()
     )
 
     plugin_dict = Dict{DataType, Plugin}()