Implement optional top bar navigation

assets/html/scss/documenter/_variables.scss

@@ -71,13 +71,12 @@ $documenter-max-width: 50rem !default;
 $documenter-sidebar-width: 18rem !default;
 
 $documenter-sidebar-main-gap: 2rem !default;
-$documenter-main-padding-right: 1rem !default;
-$documenter-main-padding: 1rem !default;
+$documenter-main-margin-right: 1rem !default;
 
 // We'll override the Bulma $tablet width, which is the point at which the
 // layout switches between the mobile and tablet modes. Note: $tablet needs
 // to be in px, hence the unit conversion.
-$desktop: round($body-size * ($documenter-max-width + $documenter-sidebar-width + $documenter-sidebar-main-gap + $documenter-main-padding-right - 5rem)/1rem) !default;
+$desktop: round($body-size * ($documenter-max-width + $documenter-sidebar-width + $documenter-sidebar-main-gap - 5rem)/1rem) !default;
 
 // Padding for admonitions and docstrings.
 // We'll try to keep the left padding consistent between the various container

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

@@ -1,3 +1,5 @@
-@import "main";
+@import "layout";
+@import "topbar";
 @import "sidebar";
+@import "main";
 @import "search";

assets/html/scss/documenter/layout/_layout.scss

@@ -0,0 +1,39 @@
+$documenter-total-width: $documenter-sidebar-width + $documenter-sidebar-main-gap + $documenter-max-width;
+
+#documenter {
+    display: grid;
+    grid-template-columns: $documenter-sidebar-width auto;
+
+    .docs-topbar {
+        grid-row: 1;
+        grid-column: 1 / 3;
+        @include touch {
+            grid-column: 1;
+        }
+    }
+    .docs-sidebar-container {
+        grid-row: 2;
+        grid-column: 1;
+        @include touch {
+            grid-row: 2;
+            grid-column: 1;
+        }
+    }
+    .docs-sidebar {
+        position: sticky;
+        top: 0;
+    }
+    .docs-main {
+        grid-row: 2;
+        grid-column: 2;
+        margin-left: $documenter-sidebar-main-gap;
+        margin-right: $documenter-main-margin-right;
+
+        @include touch {
+            grid-row: 3;
+            grid-column: 1;
+            margin-left: auto;
+            margin-right: auto;
+        }
+    }
+}

assets/html/scss/documenter/layout/_main.scss

@@ -16,20 +16,17 @@
     }
 
     @include desktop {
-      max-width: $documenter-max-width + 2*$documenter-main-padding;
-      margin-left: $documenter-sidebar-width + $documenter-sidebar-main-gap;
-      padding-right: $documenter-main-padding-right;
+      max-width: $documenter-max-width;
     }
 
     @include touch {
       width: 100%;
 
       > article {
-        max-width: $documenter-max-width + 2*$documenter-main-padding;
+        max-width: $documenter-max-width;
         margin-left: auto;
         margin-right: auto;
         margin-bottom: 1rem;
-        padding: 0 $documenter-main-padding;
       }
       > header, > nav {
         max-width: 100%;
@@ -131,11 +128,6 @@
       padding-top: 1rem;
       padding-bottom: 1rem;
 
-      @include touch {
-        padding-left: $documenter-main-padding;
-        padding-right: $documenter-main-padding;
-      }
-
       .docs-footer-nextpage, .docs-footer-prevpage {
         flex-grow: 1;
       }

assets/html/scss/documenter/layout/_sidebar.scss

@@ -1,22 +1,17 @@
-#documenter .docs-sidebar {
-  display: flex;
-  flex-direction: column;
-
-  color: $documenter-sidebar-color;
+#documenter .docs-sidebar-container {
   background-color: $documenter-sidebar-background;
   border-right: 1px solid $border;
-  padding: 0;
-  flex: 0 0 $documenter-sidebar-width;
-  z-index: 5; // make sure it's on top of the main body and top bar
+}
 
+#documenter .docs-sidebar {
+  color: $documenter-sidebar-color;
   font-size: $documenter-sidebar-size;
 
   // This is mobile-first, so our default state is that the sidebar is hidden away left
   // of the screen.
-  position: fixed;
   left: -$documenter-sidebar-width;
   width: $documenter-sidebar-width;
-  height: 100%;
+  // height: 100%;
   transition: left 0.3s;
   // Clicking on the hamburger on mobile toggles the .visible class on the sidebar
   // If enabled, we'll move the sidebar into view. As it is now floating above the
@@ -30,11 +25,6 @@
       box-shadow: none;
     }
   }
-  // In the non-mobile layout, we show the sidebar as a left panel of the dashboard.
-  @include desktop {
-    left: 0;
-    top: 0;
-  }
 
   // The top bar of the sidebar bar contains:
   // 1. Logo (optional)

assets/html/scss/documenter/layout/_topbar.scss

@@ -0,0 +1,61 @@
+#documenter .docs-topbar {
+    background-color: red;
+
+    background-color: rgb(245, 245, 245);
+    border-bottom: 1px solid #dbdbdb;
+    height: 3rem;
+    display: flex;
+
+    .docs-right {
+        display: flex;
+        white-space: nowrap;
+        gap: 1rem;
+        align-items: center;
+        margin-left: auto;
+        // It looks like this hack is needed to make Sass happy? Otherwise it refuses to
+        // properly interpolate the variables into the calc / max expressions.
+        --width: #{$documenter-total-width};
+        margin-right: calc(max(1rem, 100vw - var(--width)));
+    }
+    .docs-right a {
+        margin-left: 1rem;
+    }
+
+    a, span {
+        font-size: 0.95rem;
+        font-weight: bold;
+        color: inherit;
+    }
+
+    ul.d-megadropdown span {
+        text-decoration: underline;
+        font-weight: normal;
+    }
+
+    > ul {
+        display: flex;
+    }
+
+    > ul > li {
+        height: 3rem;
+        margin-top: auto;
+        margin-bottom: auto;
+        display: flex;
+    }
+
+    > ul > li > a {
+        margin-top: auto;
+        margin-bottom: auto;
+        display: block;
+
+        padding: 0 1rem;
+    }
+
+    > ul > li.is-active > a {
+        text-decoration: underline;
+    }
+
+    > ul > li:hover {
+        background-color: rgb(200,200,200);
+    }
+}

docs/make.jl

@@ -18,6 +18,17 @@ rewrite_changelog(;
     repo = "JuliaDocs/Documenter.jl",
 )
 
+# When including make.jl interactively in the REPL, you can call themewatch()
+# to start up a loop that checks for the SCSS files for updates, recompiles them
+# and then updates the build/assets/theme directory of the current docs.
+# This is useful when working on the SCSS styles, and you want to test them
+# by building Documenter's own docs.
+function themewatch()
+    build_assets = joinpath(@__DIR__, "build/assets/themes")
+    DocumenterTools.Themes.themewatcher_start()
+    DocumenterTools.Themes.themewatcher_start(dst = build_assets)
+end
+
 makedocs(
     modules = [Documenter, DocumenterTools, DocumenterShowcase],
     format = if "pdf" in ARGS
@@ -31,6 +42,7 @@ makedocs(
             analytics = "UA-136089579-2",
             highlights = ["yaml"],
             ansicolor = true,
+            topnavigation = true, # TODO: disable this?
         )
     end,
     build = ("pdf" in ARGS) ? "build-pdf" : "build",