@vantagecompute/docusaurus-theme 0.4.8 → 0.5.0

package/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,21 +74,26 @@ 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 |
@@ -101,8 +101,7 @@ Served from the package once `staticDir` is in your `staticDirectories`, so no s
 | `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:

package/lib/index.cjs

@@ -3,12 +3,24 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.footerLogo = exports.navbarLogo = exports.rehypeTabsTransform = exports.staticDir = void 0;
+exports.rehypeTabsTransform = exports.staticDir = exports.resolveNavbarVariant = exports.MAX_NAVBAR_LINKS = exports.LOGO_HREF = void 0;
 exports.default = themeVantage;
+exports.validateOptions = validateOptions;
 exports.getProjectVersion = getProjectVersion;
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
-function themeVantage() {
+const options_cjs_1 = require("./options.cjs");
+var options_cjs_2 = require("./options.cjs");
+Object.defineProperty(exports, "LOGO_HREF", { enumerable: true, get: function () { return options_cjs_2.LOGO_HREF; } });
+Object.defineProperty(exports, "MAX_NAVBAR_LINKS", { enumerable: true, get: function () { return options_cjs_2.MAX_NAVBAR_LINKS; } });
+Object.defineProperty(exports, "resolveNavbarVariant", { enumerable: true, get: function () { return options_cjs_2.resolveNavbarVariant; } });
+function themeVantage(context, options) {
+    const variant = (0, options_cjs_1.resolveNavbarVariant)(context.baseUrl);
+    const globalData = {
+        variant,
+        logoHref: options_cjs_1.LOGO_HREF[variant],
+        navbarLinks: options.navbarLinks,
+    };
     return {
         name: '@vantagecompute/docusaurus-theme',
         getThemePath() {
@@ -20,8 +32,20 @@ function themeVantage() {
         getClientModules() {
             return [node_path_1.default.resolve(__dirname, '../src/css/custom.css')];
         },
+        // The navbar variant and the external buttons reach the client this way.
+        // Nothing in themeConfig.navbar is read by the theme's components.
+        contentLoaded({ actions }) {
+            actions.setGlobalData(globalData);
+        },
     };
 }
+/**
+ * Docusaurus calls this before the plugin factory. Hand-rolled rather than Joi
+ * so the package carries no validation dependency; see src/options.cts.
+ */
+function validateOptions({ options, }) {
+    return (0, options_cjs_1.validateVantageThemeOptions)(options);
+}
 /**
  * Returns the absolute path to this package's static directory.
  * Add this to your `staticDirectories` in docusaurus.config.js:
@@ -53,59 +77,4 @@ function getProjectVersion() {
 }
 // Re-export the rehype utility (plain JS, lives in src/utils/)
 exports.rehypeTabsTransform = require(node_path_1.default.resolve(__dirname, '../src/utils/rehypeTabsTransform'));
-/**
- * The Vantage colour brand mark, as a path relative to a served static
- * directory. It resolves once `staticDir` is in `staticDirectories`; no site
- * needs its own copy of the SVG.
- */
-const VANTAGE_LOGO_SRC = 'img/vantage-logo-color.svg';
-/**
- * Navbar logo for a Vantage documentation site.
- *
- * ```js
- * const { navbarLogo } = require('@vantagecompute/docusaurus-theme');
- * themeConfig: { navbar: { title: 'v8x', logo: navbarLogo, items: [...] } }
- * ```
- *
- * Deliberately has no `srcDark`. The single colour mark is drawn to read on
- * both colour modes, and a second asset would only be a second thing to keep
- * in sync.
- *
- * `href` points at the docs hub rather than the marketing site: from a spoke's
- * documentation the useful "home" is the rest of the documentation. `target`
- * is `_self` so that jump replaces the tab instead of opening a new one.
- *
- * Override by spreading, never by mutating -- the object is shared by every
- * site in the process:
- *
- * ```js
- * logo: { ...navbarLogo, href: 'https://docs.vantagecompute.ai/developer/' }
- * ```
- *
- * Omit `logo` entirely to render no navbar logo.
- */
-exports.navbarLogo = {
-    alt: 'Vantage Compute Logo',
-    src: VANTAGE_LOGO_SRC,
-    href: 'https://docs.vantagecompute.ai',
-    target: '_self',
-};
-/**
- * Footer logo for a Vantage documentation site.
- *
- * ```js
- * const { footerLogo } = require('@vantagecompute/docusaurus-theme');
- * themeConfig: { footer: { style: 'dark', logo: footerLogo, links: [...] } }
- * ```
- *
- * Same mark as {@link navbarLogo}, but `href` points at the marketing site:
- * the footer is where a reader who has finished reading looks for the company.
- *
- * Override by spreading; omit `logo` to render no footer logo.
- */
-exports.footerLogo = {
-    alt: 'Vantage Compute Logo',
-    src: VANTAGE_LOGO_SRC,
-    href: 'https://vantagecompute.ai',
-};
 //# sourceMappingURL=index.cjs.map

package/lib/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.cts"],"names":[],"mappings":";;;;;;;;AAAA,0DAA6B;AAC7B,2DAA8C;AAG9C;IACE,OAAO;QACL,IAAI,EAAE,kCAAkC;QAExC,YAAY;YACV,OAAO,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QACjD,CAAC;QAED,eAAe;YACb,OAAO,CAAC,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,uCAAuC,CAAC,CAAC,CAAC;QAC5E,CAAC;QAED,gBAAgB;YACd,OAAO,CAAC,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC,CAAC;QAC5D,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACU,QAAA,SAAS,GAAG,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAE9D;;;;GAIG;AACH;IACE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAA,6BAAQ,EAAC,8BAA8B,EAAE;YACvD,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,+DAA+D;AAClD,QAAA,mBAAmB,GAAG,OAAO,CAAC,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,kCAAkC,CAAC,CAAC,CAAC;AAexG;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,4BAA4B,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACU,QAAA,UAAU,GAAc;IACnC,GAAG,EAAE,sBAAsB;IAC3B,GAAG,EAAE,gBAAgB;IACrB,IAAI,EAAE,gCAAgC;IACtC,MAAM,EAAE,OAAO;CAChB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACU,QAAA,UAAU,GAAc;IACnC,GAAG,EAAE,sBAAsB;IAC3B,GAAG,EAAE,gBAAgB;IACrB,IAAI,EAAE,2BAA2B;CAClC,CAAC"}
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.cts"],"names":[],"mappings":";;;;;;;;;AAAA,0DAA6B;AAC7B,2DAA4C;AAE5C,+CAMuB;AAGvB,6CAAgF;AAAxE,wGAAA,SAAS,OAAA;AAAE,+GAAA,gBAAgB,OAAA;AAAE,mHAAA,oBAAoB,OAAA;AAYzD,sBACE,OAAoB,EACpB,OAAoC;IAEpC,MAAM,OAAO,GAAG,IAAA,kCAAoB,EAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,MAAM,UAAU,GAA2B;QACzC,OAAO;QACP,QAAQ,EAAE,uBAAS,CAAC,OAAO,CAAC;QAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,kCAAkC;QAExC,YAAY;YACV,OAAO,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QACjD,CAAC;QAED,eAAe;YACb,OAAO,CAAC,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,uCAAuC,CAAC,CAAC,CAAC;QAC5E,CAAC;QAED,gBAAgB;YACd,OAAO,CAAC,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC,CAAC;QAC5D,CAAC;QAED,yEAAyE;QACzE,mEAAmE;QACnE,aAAa,CAAC,EAAC,OAAO,EAAC;YACrB,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,yBAAgC,EAC9B,OAAO,GAC+E;IAEtF,OAAO,IAAA,yCAA2B,EAAC,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACU,QAAA,SAAS,GAAG,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAE9D;;;;GAIG;AACH;IACE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAA,6BAAQ,EAAC,8BAA8B,EAAE;YACvD,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,+DAA+D;AAClD,QAAA,mBAAmB,GAAG,OAAO,CAAC,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,kCAAkC,CAAC,CAAC,CAAC"}

package/lib/index.d.cts

@@ -1,5 +1,22 @@
-import type { Plugin } from '@docusaurus/types';
-export default function themeVantage(): Plugin;
+import type { LoadContext, OptionValidationContext, Plugin } from '@docusaurus/types';
+import { type ResolvedVantageThemeOptions, type VantageThemeOptions } from './options.cjs';
+export type { NavbarLink, NavbarVariant, VantageThemeOptions } from './options.cjs';
+export { LOGO_HREF, MAX_NAVBAR_LINKS, resolveNavbarVariant } from './options.cjs';
+/**
+ * Shape of the global data the theme's client components read through
+ * `usePluginData('@vantagecompute/docusaurus-theme')`.
+ */
+export interface VantageThemeGlobalData {
+    variant: 'public' | 'developer';
+    logoHref: string;
+    navbarLinks: ResolvedVantageThemeOptions['navbarLinks'];
+}
+export default function themeVantage(context: LoadContext, options: ResolvedVantageThemeOptions): Plugin;
+/**
+ * Docusaurus calls this before the plugin factory. Hand-rolled rather than Joi
+ * so the package carries no validation dependency; see src/options.cts.
+ */
+export declare function validateOptions({ options, }: OptionValidationContext<VantageThemeOptions | undefined, ResolvedVantageThemeOptions>): ResolvedVantageThemeOptions;
 /**
  * Returns the absolute path to this package's static directory.
  * Add this to your `staticDirectories` in docusaurus.config.js:
@@ -19,56 +36,4 @@ export declare const staticDir: string;
  */
 export declare function getProjectVersion(): string;
 export declare const rehypeTabsTransform: any;
-/**
- * Shape of a Docusaurus navbar or footer logo entry.
- */
-export interface ThemeLogo {
-    alt: string;
-    src: string;
-    srcDark?: string;
-    href: string;
-    target?: string;
-    width?: number;
-    height?: number;
-}
-/**
- * Navbar logo for a Vantage documentation site.
- *
- * ```js
- * const { navbarLogo } = require('@vantagecompute/docusaurus-theme');
- * themeConfig: { navbar: { title: 'v8x', logo: navbarLogo, items: [...] } }
- * ```
- *
- * Deliberately has no `srcDark`. The single colour mark is drawn to read on
- * both colour modes, and a second asset would only be a second thing to keep
- * in sync.
- *
- * `href` points at the docs hub rather than the marketing site: from a spoke's
- * documentation the useful "home" is the rest of the documentation. `target`
- * is `_self` so that jump replaces the tab instead of opening a new one.
- *
- * Override by spreading, never by mutating -- the object is shared by every
- * site in the process:
- *
- * ```js
- * logo: { ...navbarLogo, href: 'https://docs.vantagecompute.ai/developer/' }
- * ```
- *
- * Omit `logo` entirely to render no navbar logo.
- */
-export declare const navbarLogo: ThemeLogo;
-/**
- * Footer logo for a Vantage documentation site.
- *
- * ```js
- * const { footerLogo } = require('@vantagecompute/docusaurus-theme');
- * themeConfig: { footer: { style: 'dark', logo: footerLogo, links: [...] } }
- * ```
- *
- * Same mark as {@link navbarLogo}, but `href` points at the marketing site:
- * the footer is where a reader who has finished reading looks for the company.
- *
- * Override by spreading; omit `logo` to render no footer logo.
- */
-export declare const footerLogo: ThemeLogo;
 //# sourceMappingURL=index.d.cts.map

package/lib/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.cts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,CAAC,OAAO,UAAU,YAAY,IAAI,MAAM,CAgB7C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,QAAuC,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAU1C;AAGD,eAAO,MAAM,mBAAmB,KAAuE,CAAC;AAExG;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AASD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,UAAU,EAAE,SAKxB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,EAAE,SAIxB,CAAC"}
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.cts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,WAAW,EAAE,uBAAuB,EAAE,MAAM,EAAC,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAIL,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACzB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAC,UAAU,EAAE,aAAa,EAAE,mBAAmB,EAAC,MAAM,eAAe,CAAC;AAClF,OAAO,EAAC,SAAS,EAAE,gBAAgB,EAAE,oBAAoB,EAAC,MAAM,eAAe,CAAC;AAEhF;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,QAAQ,GAAG,WAAW,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,2BAA2B,CAAC,aAAa,CAAC,CAAC;CACzD;AAED,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,2BAA2B,GACnC,MAAM,CA6BR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAC9B,OAAO,GACR,EAAE,uBAAuB,CAAC,mBAAmB,GAAG,SAAS,EAAE,2BAA2B,CAAC,GACtF,2BAA2B,CAE5B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,QAAuC,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAU1C;AAGD,eAAO,MAAM,mBAAmB,KAAuE,CAAC"}

package/lib/options.cjs

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Theme options and the navbar variant rule. Pure functions with no Docusaurus
+ * imports, so they are tested directly against the compiled output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOGO_HREF = exports.MAX_NAVBAR_LINKS = void 0;
+exports.resolveNavbarVariant = resolveNavbarVariant;
+exports.validateVantageThemeOptions = validateVantageThemeOptions;
+const DEFAULT_PLUGIN_ID = 'default';
+/** Two is GitHub plus one registry (PyPI, npm, ...). More than that is a nav, and navs drift. */
+exports.MAX_NAVBAR_LINKS = 2;
+/**
+ * Where the brand mark links, per variant. Baked in on purpose: a site cannot
+ * point its logo anywhere else, which is what keeps the hub consistent.
+ */
+exports.LOGO_HREF = {
+    public: 'https://docs.vantagecompute.ai/',
+    developer: 'https://docs.vantagecompute.ai/developer/',
+};
+/**
+ * Every site published under /developer/ (the developer overview and every
+ * spoke) gets the developer navbar. Everything else gets the public one.
+ * Docusaurus normalises baseUrl to a leading and trailing slash before the
+ * plugin sees it.
+ */
+function resolveNavbarVariant(baseUrl) {
+    return baseUrl.startsWith('/developer/') ? 'developer' : 'public';
+}
+const PREFIX = '[@vantagecompute/docusaurus-theme]';
+function fail(message) {
+    throw new Error(`${PREFIX} ${message}`);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function validateLink(value, index) {
+    const where = `navbarLinks[${index}]`;
+    if (!isPlainObject(value)) {
+        fail(`${where} must be an object with "label" and "url".`);
+    }
+    const extra = Object.keys(value).filter((key) => key !== 'label' && key !== 'url');
+    if (extra.length > 0) {
+        fail(`${where} has unsupported propert${extra.length === 1 ? 'y' : 'ies'} ` +
+            `${extra.map((k) => `"${k}"`).join(', ')}. Only "label" and "url" are ` +
+            `accepted; the icon, external-link marker and rel attributes come from the theme.`);
+    }
+    const { label, url } = value;
+    if (typeof label !== 'string' || label.trim() === '') {
+        fail(`${where}.label must be a non-empty string.`);
+    }
+    if (typeof url !== 'string' || url.trim() === '') {
+        fail(`${where}.url must be a non-empty string.`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return fail(`${where}.url must be an absolute http(s) URL, got "${url}".`);
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        fail(`${where}.url must be an absolute http(s) URL, got "${url}".`);
+    }
+    return { label: label.trim(), url };
+}
+/**
+ * Validate and normalise the theme options. Throws with a message that names
+ * the offending key, so a misconfigured spoke fails its build instead of
+ * quietly rendering something off-convention.
+ */
+function validateVantageThemeOptions(options) {
+    if (options === undefined || options === null) {
+        return { id: DEFAULT_PLUGIN_ID, navbarLinks: [] };
+    }
+    if (!isPlainObject(options)) {
+        fail('theme options must be an object.');
+    }
+    const { navbarLinks, id, ...unknown } = options;
+    const unknownKeys = Object.keys(unknown);
+    if (unknownKeys.length > 0) {
+        fail(`unknown option${unknownKeys.length === 1 ? '' : 's'} ` +
+            `${unknownKeys.map((k) => `"${k}"`).join(', ')}. The only option is "navbarLinks".`);
+    }
+    const resolved = {
+        id: typeof id === 'string' ? id : DEFAULT_PLUGIN_ID,
+        navbarLinks: [],
+    };
+    if (navbarLinks === undefined) {
+        return resolved;
+    }
+    if (!Array.isArray(navbarLinks)) {
+        fail('"navbarLinks" must be an array of {label, url} objects.');
+    }
+    if (navbarLinks.length > exports.MAX_NAVBAR_LINKS) {
+        fail(`"navbarLinks" allows at most ${exports.MAX_NAVBAR_LINKS} entries, got ${navbarLinks.length}. ` +
+            `GitHub plus one package registry is the intended use.`);
+    }
+    resolved.navbarLinks = navbarLinks.map(validateLink);
+    return resolved;
+}
+//# sourceMappingURL=options.cjs.map

package/lib/options.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.cjs","sourceRoot":"","sources":["../src/options.cts"],"names":[],"mappings":"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"}

package/lib/options.d.cts

@@ -0,0 +1,46 @@
+/**
+ * Theme options and the navbar variant rule. Pure functions with no Docusaurus
+ * imports, so they are tested directly against the compiled output.
+ */
+export type NavbarVariant = 'public' | 'developer';
+/** One external button in the developer navbar. Nothing else is configurable. */
+export interface NavbarLink {
+    label: string;
+    url: string;
+}
+/** What a site may pass in `themes: [['@vantagecompute/docusaurus-theme', {...}]]`. */
+export interface VantageThemeOptions {
+    /** External buttons, at most {@link MAX_NAVBAR_LINKS}. Rendered by the developer navbar only. */
+    navbarLinks?: NavbarLink[];
+}
+/**
+ * Options after validation. `id` is Docusaurus's plugin-instance id. When a
+ * plugin exports validateOptions, Docusaurus trusts the returned object to
+ * carry it (its own Joi path adds one), and names the plugin's generated data
+ * directory after it. Leaving it out crashes the build in path.join.
+ */
+export interface ResolvedVantageThemeOptions {
+    id: string;
+    navbarLinks: NavbarLink[];
+}
+/** Two is GitHub plus one registry (PyPI, npm, ...). More than that is a nav, and navs drift. */
+export declare const MAX_NAVBAR_LINKS = 2;
+/**
+ * Where the brand mark links, per variant. Baked in on purpose: a site cannot
+ * point its logo anywhere else, which is what keeps the hub consistent.
+ */
+export declare const LOGO_HREF: Record<NavbarVariant, string>;
+/**
+ * Every site published under /developer/ (the developer overview and every
+ * spoke) gets the developer navbar. Everything else gets the public one.
+ * Docusaurus normalises baseUrl to a leading and trailing slash before the
+ * plugin sees it.
+ */
+export declare function resolveNavbarVariant(baseUrl: string): NavbarVariant;
+/**
+ * Validate and normalise the theme options. Throws with a message that names
+ * the offending key, so a misconfigured spoke fails its build instead of
+ * quietly rendering something off-convention.
+ */
+export declare function validateVantageThemeOptions(options: unknown): ResolvedVantageThemeOptions;
+//# sourceMappingURL=options.d.cts.map

package/lib/options.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.cts","sourceRoot":"","sources":["../src/options.cts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEnD,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,iGAAiG;IACjG,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAID,iGAAiG;AACjG,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAGnD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAEnE;AAgDD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,2BAA2B,CAqCzF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantagecompute/docusaurus-theme",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "description": "Shared Vantage Compute Docusaurus theme: design system, brand assets, and common theme overrides for all vantagecompute documentation sites.",
   "license": "MIT",
   "main": "lib/index.cjs",
@@ -12,6 +12,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "node --test 'test/**/*.test.cjs'",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {