Top menu from pages

CHANGELOG.md

@@ -14,6 +14,7 @@ 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])

assets/html/js/sidebar.js

@@ -3,7 +3,7 @@
 
 // Manages the showing and hiding of the sidebar.
 $(document).ready(function () {
-  var sidebar = $("#documenter > .docs-sidebar");
+  var sidebar = $("#documenter .docs-sidebar");
   var sidebar_button = $("#documenter-sidebar-button");
   sidebar_button.click(function (ev) {
     ev.preventDefault();
@@ -13,7 +13,7 @@ $(document).ready(function () {
       $("#documenter .docs-menu a.is-active").focus();
     }
   });
-  $("#documenter > .docs-main").bind("click", function (ev) {
+  $("#documenter .docs-main").bind("click", function (ev) {
     if ($(ev.target).is(sidebar_button)) {
       return;
     }
@@ -42,6 +42,32 @@ $(document).ready(function () {
   $(window).on("orientationchange", resize);
 });
 
+// Dynamically update --topmenu-height so that the sidebar, content wrapper, and
+// sticky navbar all stay correctly positioned when top menu items wrap to a new line.
+$(document).ready(function () {
+  var topMenu = $("#documenter .docs-top-menu");
+  if (topMenu.length === 0) return;
+  var documenter = document.getElementById("documenter");
+  function updateTopMenuHeight() {
+    var height = topMenu[0].offsetHeight + "px";
+    documenter.style.setProperty("--topmenu-height", height);
+    // Offset anchor-scroll targets so the fixed top menu doesn't cover them
+    document.documentElement.style.scrollPaddingTop = height;
+  }
+  updateTopMenuHeight();
+  $(window).resize(updateTopMenuHeight);
+  $(window).on("orientationchange", updateTopMenuHeight);
+  // Re-scroll to the hash anchor now that scroll-padding-top is set.
+  // The browser may have already scrolled to the anchor before JS ran,
+  // causing the header to be hidden under the fixed top menu.
+  if (location.hash) {
+    var target = document.getElementById(
+      decodeURIComponent(location.hash.substring(1))
+    );
+    if (target) target.scrollIntoView();
+  }
+});
+
 // Scroll the navigation bar to the currently selected menu item
 $(document).ready(function () {
   var sidebar = $("#documenter .docs-menu").get(0);

assets/html/scss/documenter/layout/_all.scss

@@ -1,3 +1,4 @@
 @import "main";
 @import "sidebar";
 @import "search";
+@import "topmenu";

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

@@ -0,0 +1,214 @@
+// Top Menu Navigation Bar
+// This provides the top-level section navigation when top_menu is configured
+// Uses the same color scheme as the sidebar for consistency across themes
+
+// Variables for top menu - derived from sidebar variables for theme consistency
+$documenter-topmenu-height: 2.75rem !default;
+$documenter-topmenu-background: $documenter-sidebar-background !default;
+$documenter-topmenu-color: $documenter-sidebar-color !default;
+$documenter-topmenu-hover-background: $documenter-sidebar-menu-hover-background !default;
+$documenter-topmenu-hover-color: $documenter-sidebar-menu-hover-color !default;
+$documenter-topmenu-active-background: $documenter-sidebar-menu-active-background !default;
+$documenter-topmenu-active-color: $documenter-sidebar-menu-active-color !default;
+
+// Top menu navigation bar
+.docs-top-menu {
+  background-color: $documenter-topmenu-background;
+  min-height: $documenter-topmenu-height; // Allow growing when items wrap
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 100; // Above sidebar and main content
+  display: flex;
+  align-items: flex-start;
+  border-bottom: 1px solid $border;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+
+  .container {
+    width: 100%;
+    max-width: none;
+    padding: 0;
+    margin: 0;
+  }
+
+  .docs-top-menu-list {
+    display: flex;
+    flex-direction: row;
+    flex-wrap: wrap; // Allow items to wrap to a new line when space is tight
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    gap: 0;
+    // Keep overflow visible so absolutely-positioned dropdown menus are not clipped.
+    overflow: visible;
+    height: auto;
+
+    > li {
+      flex-shrink: 0;
+      display: flex;
+      align-items: stretch;
+
+      &.is-active {
+        .docs-top-menu-link {
+          background-color: $documenter-topmenu-active-background;
+          color: $documenter-topmenu-active-color;
+          font-weight: 700;
+          border-bottom: 3px solid $primary;
+        }
+      }
+    }
+  }
+
+  .docs-top-menu-link {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0 1.5rem;
+    color: $documenter-topmenu-color;
+    text-decoration: none;
+    white-space: nowrap;
+    font-size: 0.95rem;
+    font-weight: 500;
+    letter-spacing: 0.02em;
+    height: $documenter-topmenu-height;
+    transition: background-color 0.15s ease, color 0.15s ease;
+    border-bottom: 3px solid transparent;
+
+    &:hover {
+      background-color: $documenter-topmenu-hover-background;
+      color: $documenter-topmenu-hover-color;
+      text-decoration: none;
+    }
+
+    .docs-top-dropdown-caret {
+      margin-left: 0.35em;
+      font-size: 0.75em;
+      opacity: 0.6;
+      line-height: 1;
+    }
+  }
+
+  // Dropdown menu for each top-menu item
+  .docs-top-dropdown {
+    position: relative;
+
+    .docs-top-dropdown-menu {
+      display: none;
+      position: absolute;
+      top: 100%;
+      left: 0;
+      min-width: 14rem;
+      background-color: $documenter-topmenu-background;
+      border: 1px solid $border;
+      border-radius: 0 0 4px 4px;
+      box-shadow: 0 4px 10px rgba(0, 0, 0, 0.12);
+      z-index: 200;
+      padding: 0.3rem 0;
+      list-style: none;
+      margin: 0;
+
+      > li > .docs-top-dropdown-item {
+        display: block;
+        padding: 0.45rem 1rem;
+        color: $documenter-topmenu-color;
+        text-decoration: none;
+        font-size: 0.875rem;
+        white-space: nowrap;
+        transition: background-color 0.1s ease, color 0.1s ease;
+
+        &:hover {
+          background-color: $documenter-topmenu-hover-background;
+          color: $documenter-topmenu-hover-color;
+          text-decoration: none;
+        }
+      }
+    }
+
+    // Show dropdown on hover (desktop) and when focus is inside (keyboard navigation)
+    &:hover > .docs-top-dropdown-menu,
+    &:focus-within > .docs-top-dropdown-menu {
+      display: block;
+    }
+  }
+}
+
+// Adjustments when top menu is present
+#documenter.has-top-menu {
+  // Content wrapper to hold sidebar and main content
+  .docs-content-wrapper {
+    display: flex;
+    padding-top: var(--topmenu-height, #{$documenter-topmenu-height});
+    min-height: 100vh;
+  }
+
+  // Adjust sidebar position
+  .docs-sidebar {
+    top: var(--topmenu-height, #{$documenter-topmenu-height});
+    height: calc(100vh - var(--topmenu-height, #{$documenter-topmenu-height}));
+
+    @include desktop {
+      top: var(--topmenu-height, #{$documenter-topmenu-height});
+    }
+  }
+
+  // Adjust main content area
+  .docs-main {
+    flex: 1;
+    min-width: 0;
+
+    @include desktop {
+      // Adjust for sidebar width when visible
+      margin-left: $documenter-sidebar-width + $documenter-sidebar-main-gap;
+    }
+  }
+}
+
+// Mobile adjustments
+@include touch {
+  .docs-top-menu {
+    min-height: 2.5rem; // Slightly smaller on mobile; auto-grows when items wrap
+
+    .docs-top-menu-list {
+      // Allow wrapping on narrow screens instead of hiding items off-screen
+      flex-wrap: wrap;
+      justify-content: flex-start;
+      padding: 0 0.5rem;
+    }
+
+    .docs-top-menu-link {
+      padding: 0 1rem;
+      font-size: 0.875rem;
+      height: 2.5rem;
+    }
+
+    // Hide dropdowns on touch devices — they don't work with hover-only interaction
+    .docs-top-dropdown-menu {
+      display: none !important;
+    }
+    .docs-top-dropdown-caret {
+      display: none;
+    }
+  }
+
+  #documenter.has-top-menu {
+    .docs-content-wrapper {
+      padding-top: var(--topmenu-height, 2.5rem);
+    }
+
+    .docs-sidebar {
+      // On mobile, sidebar is overlay, needs to account for top menu
+      top: var(--topmenu-height, 2.5rem);
+      height: calc(100vh - var(--topmenu-height, 2.5rem));
+    }
+
+    .docs-main {
+      margin-left: 0;
+
+      > header.docs-navbar {
+        // Sticky navbar on mobile needs to account for top menu
+        top: var(--topmenu-height, 2.5rem);
+      }
+    }
+  }
+}

docs/Project.toml

@@ -2,7 +2,8 @@
 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

@@ -438,6 +438,65 @@ Using the `pages` argument you can organize your pages into subsections and hide
 from the sidebar with the help of the [`hide`](@ref) functions.
 
 
+## 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.
+
+```julia
+makedocs(
+    ...,
+    top_menu = true,
+    pages = [
+        "Getting Started" => [
+            "Home" => "index.md",
+            "Installation" => "getting-started/install.md",
+            "Quick Start" => "getting-started/quickstart.md",
+        ],
+        "User Guide" => [
+            "Overview" => "guide/index.md",
+            "Basic Usage" => "guide/basics.md",
+            "Advanced Topics" => [
+                "guide/advanced.md",
+                "guide/tips.md",
+            ],
+        ],
+        "API Reference" => [
+            "Public API" => "api/public.md",
+            "Internals" => "api/internals.md",
+        ],
+    ],
+)
+```
+
+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.
+
+- 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
+
+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.).
+
+!!! 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.
+
+!!! 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.
+
+If `top_menu = false` (the default), Documenter uses the standard single-sidebar
+behavior controlled by the `pages` argument.
+
+
 ## Adding a logo or icon
 
 You can easily add a logo or icon to your documentation which