feat: theme-owned navbars, navbarLinks option, and no footer (0.5.0)

.github/workflows/ci.yml

@@ -39,6 +39,10 @@ jobs:
 
       - run: yarn build
 
+      # The option validator is tested against lib/, the compiled output
+      # consumers get, so this has to follow the build.
+      - run: yarn test
+
       # `files` in package.json decides what reaches consumers, and it is the
       # one thing a successful `tsc` says nothing about. Pack the tarball and
       # assert the assets the design system references are inside it, so a file
@@ -52,6 +56,7 @@ jobs:
           for asset in \
             lib/index.cjs \
             lib/index.d.cts \
+            lib/options.cjs \
             src/css/custom.css \
             src/utils/rehypeTabsTransform.js \
             static/fonts/Satoshi-Regular.woff \

MIGRATION.md

@@ -1,6 +1,6 @@
 # Migrating to @vantagecompute/docusaurus-theme
 
-Two migrations live here:
+Four migrations live here:
 
 - **[Part 1: adopting the theme](#part-1-adopting-the-theme)** walks the
   `vantage-docs` project through its first move onto the shared package. Any
@@ -10,6 +10,9 @@ Two migrations live here:
   logo and its own navbar/footer logo config. Added in 0.4.7.
 - **[Part 3: small screens](#part-3-small-screens-049)** is for a site that
   papered over the theme's phone and tablet defects itself. Added in 0.4.9.
+- **[Part 4: the theme-owned navbar](#part-4-the-theme-owned-navbar-050)**
+  is for a site on 0.4.x that declares its own `themeConfig.navbar` or
+  `footer`. Added in 0.5.0.
 
 ## Part 1: adopting the theme
 
@@ -317,3 +320,73 @@ At 375, 768 and 1024 wide:
 - [ ] A wide reference table scrolls inside its frame rather than squeezing
 - [ ] Every tab in a tab strip is visible
 - [ ] At 1024 the article has no right-hand TOC column and shows the "On this page" collapsible instead
+
+## Part 4: the theme-owned navbar (0.5.0)
+
+From 0.5.0 the theme renders the navbar itself and renders no footer. A site's
+`themeConfig.navbar` and `themeConfig.footer` are ignored, and the
+`navbarLogo`, `footerLogo` and `ThemeLogo` exports are gone. This is the
+breaking change behind the minor bump.
+
+### Step 1: Upgrade the package
+
+```bash
+npm install @vantagecompute/docusaurus-theme@^0.5.0
+```
+
+### Step 2: Move your external buttons to the theme option
+
+```diff
+- themes: ['@docusaurus/theme-mermaid', '@vantagecompute/docusaurus-theme'],
++ themes: [
++   '@docusaurus/theme-mermaid',
++   ['@vantagecompute/docusaurus-theme', {
++     navbarLinks: [
++       {label: 'GitHub', url: 'https://github.com/vantagecompute/my-project'},
++       {label: 'PyPI', url: 'https://pypi.org/project/my-project/'},
++     ],
++   }],
++ ],
+```
+
+Two at most, `label` and `url` only. Anything else in your old `items` (doc
+links, dropdowns, a search item) has no equivalent; the developer navbar does
+not carry them, by design.
+
+### Step 3: Delete the navbar and footer blocks
+
+```diff
+- const {staticDir, navbarLogo, footerLogo, getProjectVersion} = require('@vantagecompute/docusaurus-theme');
++ const {staticDir, getProjectVersion} = require('@vantagecompute/docusaurus-theme');
+
+  themeConfig: {
+-   navbar: {
+-     title: 'my-project',
+-     logo: navbarLogo,
+-     items: [...],
+-   },
+-   footer: {...},
+    prism: {...},
+  },
+```
+
+The centred title now comes from `siteConfig.title`, so make sure that is the
+name you want beside the version badge. The version badge still reads
+`customFields.projectVersion`.
+
+### Step 4: Delete any local navbar swizzle
+
+If your `src/theme/` has `Navbar/Content`, `Navbar/Logo`,
+`Navbar/MobileSidebar/PrimaryMenu` or `Footer`, delete them; a local copy
+silently wins over the theme's.
+
+### Step 5: Verify
+
+```bash
+npm run build
+```
+
+Then open the site: the brand mark links to `/developer/` (or the docs root
+on the main site), your buttons open in a new tab with the external-link icon,
+and there is no footer. A misconfigured `navbarLinks` fails the build with a
+message naming the entry.

README.md

@@ -16,8 +16,6 @@ Add the theme to your `docusaurus.config.js`:
 const {
   staticDir,
   rehypeTabsTransform,
-  navbarLogo,
-  footerLogo,
   getProjectVersion,
 } = require('@vantagecompute/docusaurus-theme');
 
@@ -30,8 +28,16 @@ const config = {
   // grows and shrinks reflows the header on every release.
   tagline: `What this project does (${projectVersion})`,
 
-  // Add the Vantage theme
-  themes: ['@vantagecompute/docusaurus-theme'],
+  // Add the Vantage theme. Its one option is the external buttons on the
+  // developer navbar: at most two, each a label and an absolute url.
+  themes: [
+    ['@vantagecompute/docusaurus-theme', {
+      navbarLinks: [
+        {label: 'GitHub', url: 'https://github.com/vantagecompute/my-project'},
+        {label: 'PyPI', url: 'https://pypi.org/project/my-project/'},
+      ],
+    }],
+  ],
 
   // Serve shared static assets (fonts, icons, brand mark)
   staticDirectories: ['static', staticDir],
@@ -47,24 +53,13 @@ const config = {
   ],
 
   themeConfig: {
-    navbar: {
-      title: 'my-project',
-      logo: navbarLogo,
-      items: [/* ... */],
-    },
-    footer: {
-      style: 'dark',
-      logo: footerLogo,
-      links: [/* ... */],
-    },
+    // No navbar and no footer here: the theme renders both. A site under
+    // /developer/ gets the developer navbar, anything else the public one.
+    prism: {/* ... */},
   },
 };
 ```
 
-`navbarLogo` and `footerLogo` carry the Vantage brand mark, its alt text, and
-the right link target for each position. Your site needs no copy of the SVG:
-it is served out of `staticDir`.
-
 ## What's included
 
 ### Design System CSS
@@ -79,30 +74,34 @@ Served from the package once `staticDir` is in your `staticDirectories`, so no s
 - **Fonts**: Satoshi (Regular, Medium, Bold + italics) as `.woff` files
 - **Icons**: Sun/moon toggles, search, external link, GitHub, chevron SVGs
 - **Brand mark**: `vantage-logo-color.svg`, the current Vantage mark, used by
-  `navbarLogo` and `footerLogo`. It has no dark variant on purpose: the one
-  colour mark is drawn to read in both colour modes.
+  the theme's navbar. It has no dark variant on purpose: the one colour mark
+  is drawn to read in both colour modes.
 - **Legacy logo**: `vantage-logo.svg`, the older monochrome mark. Kept for the
   `vantage-docs` hub, which still points at it. New sites should use the
   brand mark above.
 - **Favicon**: `favicon.ico`
 
 ### Theme Component Overrides
-| Component | Description |
+| Component | What it changes |
 |---|---|
-| `ColorModeToggle` | Custom sun/moon SVG icon toggle |
-| `DocBreadcrumbs` | Full-path breadcrumb rendering |
-| `Navbar/Logo` | Centered site title with the version badge beside it |
-| `Tabs` | Bugfix for Docusaurus 3.10 whitespace crash |
-| `Navbar/MobileSidebar/SecondaryMenu` | Clean secondary menu render |
+| `Navbar/Content` | The whole navbar, in a public or a developer variant chosen from `baseUrl` (0.5.0) |
+| `Navbar/Logo` | The brand link with the variant's baked href, the centred title and the version badge |
+| `Navbar/MobileSidebar/PrimaryMenu` | The developer navbar's external buttons, in the mobile drawer (0.5.0) |
+| `Navbar/SiteActions` | An empty slot in the public navbar for a site's own controls (0.5.0) |
+| `Navbar/MobileSidebar/SecondaryMenu` | A clean secondary-menu render |
+| `Footer` | Renders nothing (0.5.0) |
+| `ColorModeToggle` | Sun and moon SVG icons in place of the default toggle |
+| `DocBreadcrumbs` | Full-path breadcrumbs instead of the truncated default |
+| `Tabs` | A workaround for a Docusaurus 3.10 crash |
+| `MDXComponents` | Every markdown `table` renders inside a horizontal scroll region (0.4.9) |
 
 ### Utilities
 | Export | Description |
 |---|---|
 | `staticDir` | Absolute path to this package's `static/` directory; add it to `staticDirectories` |
 | `rehypeTabsTransform` | Rehype plugin that transforms lowercase `<tabs>`/`<tabitem>` to React components |
 | `getProjectVersion()` | Project version inferred from git tags (`git describe --tags --always`), or `"dev"` |
-| `navbarLogo` | Navbar logo config: the brand mark, linking to `https://docs.vantagecompute.ai` |
-| `footerLogo` | Footer logo config: the same mark, linking to `https://vantagecompute.ai` |
+| `resolveNavbarVariant(baseUrl)` | The rule that picks the public or developer navbar; exported for tooling |
 
 ## Customization
 
@@ -117,19 +116,21 @@ your-docs-site/
         index.js
 ```
 
-### Overriding the logo
-
-`navbarLogo` and `footerLogo` are plain objects. Spread one to change a field,
-and leave the rest to the theme:
+### Navbar buttons
 
 ```js
-navbar: {
-  logo: { ...navbarLogo, href: 'https://docs.vantagecompute.ai/developer/' },
-},
+themes: [
+  ['@vantagecompute/docusaurus-theme', {
+    navbarLinks: [
+      {label: 'GitHub', url: 'https://github.com/vantagecompute/my-project'},
+      {label: 'PyPI', url: 'https://pypi.org/project/my-project/'},
+    ],
+  }],
+],
 ```
 
-Spread rather than mutate: the objects are shared by everything that imports
-them. To render no logo at all, just omit `logo`.
+That is the whole navbar surface a site has. See the docs site's Customization
+page for the public navbar's `SiteActions` slot.
 
 ### Extending CSS
 Add your own CSS in `src/css/custom.css` and reference it in your preset config. Your styles will layer on top of the shared design system: