@nubisco/docs-sdk 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Nubisco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="fixture/docs/public/logo.svg" alt="Nubisco" width="96" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">@nubisco/docs-sdk</h1>
+
+<p align="center">The Nubisco documentation design as one package: VitePress, the theme, the plugins and a config helper. A product supplies its content and a small config.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@nubisco/docs-sdk"><img src="https://img.shields.io/npm/v/@nubisco/docs-sdk" alt="npm" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/@nubisco/docs-sdk" alt="license" /></a>
+</p>
+
+## What it gives you
+
+- **The design.** Neutral layer colours, a page header that is an inset card and closes
+  into a bar as you scroll, tabs that are pages, a left navigation with a filter, and
+  "On this page" on the right. Light, dark and auto.
+- **VitePress, bundled.** Your project depends on this package, not on VitePress. One
+  version of VitePress across every site.
+- **The plugins.** Tabs, mermaid diagrams and grouped code icons, already wired.
+- **A config helper.** `defineNubiscoDocs` sets everything the design fixes. You state
+  your name, address, repository, navigation and footer.
+- **A CLI.** `nubisco-docs dev | build | preview`.
+
+## Install
+
+```sh
+pnpm add -D @nubisco/docs-sdk @nubisco/ui vue
+```
+
+`@nubisco/ui` and `vue` are peer dependencies: the theme is built from the library's
+components and tokens, and there must be one copy of each.
+
+## Use
+
+```ts
+// docs/.vitepress/config.ts
+import { defineNubiscoDocs } from '@nubisco/docs-sdk'
+
+export default defineNubiscoDocs({
+  title: 'Acta',
+  description: 'What Acta is, in one sentence.',
+  base: '/acta/',
+  hostname: 'https://docs.nubisco.io/acta/',
+  repo: 'nubisco/acta',
+  nav: [
+    { text: 'Users', link: '/users/' },
+    { text: 'Developers', link: '/developers/' },
+  ],
+  sidebar: {
+    '/users/': [
+      { text: 'Start', items: [{ text: 'Welcome', link: '/users/' }] },
+    ],
+  },
+  footer: {
+    copyright: 'Copyright © 2026 <a href="https://nubisco.io">Nubisco</a>',
+  },
+})
+```
+
+```ts
+// docs/.vitepress/theme/index.ts
+import theme from '@nubisco/docs-sdk/theme'
+export default theme
+```
+
+```json
+{
+  "scripts": {
+    "docs:dev": "nubisco-docs dev",
+    "docs:build": "nubisco-docs build"
+  }
+}
+```
+
+Pages opt in with `layout: nubisco` in frontmatter. The fields the layout reads are
+`title`, `intro` (one paragraph of inline Markdown), `status` (`stable`, `beta`, `labs`...),
+`source` (a path in the repository, for the source link) and, for a page with facets,
+`pageTabs` plus `tab`.
+
+The `fixture/` folder is a complete small site that uses the package exactly as above. It is
+built in CI on every change.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Contributions are made under the
+[Contributor License Agreement](docs/CLA-INDIVIDUAL.md). Security reports: see
+[SECURITY.md](SECURITY.md).
+
+## Acknowledgements
+
+The layout draws inspiration from [IBM Carbon Design System](https://carbondesignsystem.com)
+documentation structure. Carbon is the work of IBM and its contributors, licensed under Apache 2.0.
+The tabs and mermaid plugins are adapted from `vitepress-plugin-tabs` and
+`vitepress-plugin-mermaid`, both MIT. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+---
+
+## License
+
+[MIT](LICENSE)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,100 @@
+# Third-party notices
+
+`@nubisco/docs-sdk` is released under the MIT License (see `LICENSE`). It contains code
+adapted from the projects below, and it is used with the fonts and libraries listed at
+the end. Each keeps its own licence and copyright, reproduced here as those licences
+require.
+
+## Code adapted into this package
+
+### vitepress-plugin-tabs
+
+Adapted into `src/plugins/tabs/` (the tabs markdown rule and the tab components).
+Source: https://github.com/sapphi-red/vitepress-plugins (package `vitepress-plugin-tabs`, MIT).
+
+```
+MIT License
+
+Copyright (c) 2022 sapphi-red
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+### vitepress-plugin-mermaid
+
+Adapted into `src/plugins/mermaid/` (the mermaid markdown rule, the Vite plugin and the
+diagram component). Source: https://github.com/emersonbottero/vitepress-plugin-mermaid
+(package `vitepress-plugin-mermaid`, MIT).
+
+```
+MIT License
+
+Copyright (c) 2022 emersonbottero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## Design reference (no code taken)
+
+The layout draws on the structure of the documentation of IBM's Carbon Design System
+(https://carbondesignsystem.com), which is the work of IBM and its contributors and is
+licensed under Apache 2.0. This package contains none of Carbon's code, assets or marks.
+"Carbon" and "IBM" are trademarks of International Business Machines Corporation.
+
+## Dependencies
+
+Installed with this package, not copied into it. Their licences travel with them.
+
+| Package | Licence |
+| --- | --- |
+| `vitepress`, `vue`, `vite`, `mermaid`, `vite-svg-loader`, `vitepress-plugin-group-icons`, `markdown-it-container`, `sass-embedded` | MIT |
+| `@nubisco/ui` (peer dependency) | MIT |
+| `@fontsource/plus-jakarta-sans` (Plus Jakarta Sans) | SIL Open Font License 1.1 |
+| `@fontsource/fira-code` (Fira Code) | SIL Open Font License 1.1 |
+
+### Fonts
+
+The sites this package builds serve Plus Jakarta Sans (Copyright 2020 The Plus Jakarta
+Sans Project Authors, https://github.com/tokotype/PlusJakartaSans) and Fira Code
+(Copyright 2014-2020 The Fira Code Project Authors, https://github.com/tonsky/FiraCode),
+both under the SIL Open Font License, Version 1.1
+(https://openfontlicense.org). The fonts are not part of this package's own files: they
+come from the `@fontsource` packages, which carry the full licence text. A site that
+republishes the font files keeps that licence file with them.
+
+### Icons
+
+The icons the theme draws come from `@nubisco/ui`, which builds them from Phosphor Icons
+(https://phosphoricons.com, MIT, Copyright (c) 2023 Phosphor Icons).

package/dist/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+// src/node/cli.ts
+import { build, createServer, serve } from "vitepress";
+var USAGE = `nubisco-docs <command> [root] [--port <n>]
+
+  dev       start the dev server
+  build     build the static site
+  preview   serve a built site
+
+root is the docs folder, "docs" by default.`;
+var [command, ...rest] = process.argv.slice(2);
+var flagAt = rest.indexOf("--port");
+var port = flagAt === -1 ? void 0 : Number(rest[flagAt + 1]);
+var root = rest.find((arg, i) => !arg.startsWith("--") && rest[i - 1] !== "--port") ?? "docs";
+async function main() {
+  if (command === "dev") {
+    const server = await createServer(root, { port });
+    await server.listen();
+    server.printUrls();
+  } else if (command === "build") {
+    await build(root);
+  } else if (command === "preview") {
+    await serve({ root, port });
+  } else {
+    console.error(USAGE);
+    process.exit(command ? 1 : 0);
+  }
+}
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { DefaultTheme, UserConfig } from 'vitepress';
+
+/** What the Nubisco theme reads from `themeConfig.nubisco`. */
+interface INubiscoDocsThemeConfig {
+    /** `owner/name` on GitHub. Drives the source and issue links in the page header. */
+    repo?: string;
+    /** The branch the source links point at. Defaults to `master`. */
+    branch?: string;
+    /**
+     * Show the Square and Round switch beside the colour mode. It belongs to the
+     * component library's own docs and is off everywhere else.
+     */
+    appearanceControl?: boolean;
+}
+interface INubiscoDocsOptions {
+    /** The product's name, shown in the top bar and the page header. */
+    title: string;
+    /** One sentence, for search engines and link previews. */
+    description: string;
+    /** URL prefix the site is served under, with both slashes: `/acta/`. */
+    base: string;
+    /** The public address of the site, for the sitemap: `https://docs.nubisco.io/acta/`. */
+    hostname: string;
+    /** `owner/name` on GitHub: `nubisco/acta`. */
+    repo: string;
+    /** Branch the edit and source links point at. Defaults to `master`. */
+    branch?: string;
+    /** Folder of the docs inside the repository, for the edit link. Defaults to `docs/`. */
+    docsDir?: string;
+    /** Path of the product's mark under `public/`. Defaults to `/logo.svg`. */
+    logo?: string;
+    /** Browser chrome colour. Defaults to the dark ground. */
+    themeColor?: string;
+    /** The top bar's links, in the order the standard sets (see the docs standard). */
+    nav: DefaultTheme.NavItem[];
+    /** The left navigation. Keyed by path prefix, or one list. */
+    sidebar: DefaultTheme.Sidebar;
+    /** HTML for the two footer lines. Links are allowed. */
+    footer?: {
+        message?: string;
+        copyright?: string;
+    };
+    /** Analytics script. Nubisco's by default, `false` for none. */
+    analytics?: string | false;
+    /** Show the Square and Round switch. Component library only. */
+    appearanceControl?: boolean;
+    /**
+     * Anything else VitePress accepts, merged over the defaults. `vite` and
+     * `themeConfig` are merged one level deep, `head` is appended, and a
+     * `markdown.config` is called after the SDK's own.
+     */
+    vitepress?: UserConfig<DefaultTheme.Config>;
+}
+
+/**
+ * The VitePress config for a Nubisco product's documentation.
+ *
+ * ```ts
+ * // docs/.vitepress/config.ts
+ * import { defineNubiscoDocs } from '@nubisco/docs-sdk'
+ *
+ * export default defineNubiscoDocs({
+ *   title: 'Acta',
+ *   description: '…',
+ *   base: '/acta/',
+ *   hostname: 'https://docs.nubisco.io/acta/',
+ *   repo: 'nubisco/acta',
+ *   nav: [...],
+ *   sidebar: { ... },
+ * })
+ * ```
+ *
+ * Everything the design standard fixes is set here, so a product states only
+ * what is its own: its name, its address, its navigation and its footer.
+ */
+declare function defineNubiscoDocs(options: INubiscoDocsOptions): UserConfig<DefaultTheme.Config>;
+
+export { type INubiscoDocsOptions, type INubiscoDocsThemeConfig, defineNubiscoDocs };

package/dist/index.js

@@ -0,0 +1,361 @@
+// src/node/index.ts
+import { defineConfig } from "vitepress";
+import svgLoader from "vite-svg-loader";
+import {
+  groupIconMdPlugin,
+  groupIconVitePlugin
+} from "vitepress-plugin-group-icons";
+import { nubiscoUI } from "@nubisco/ui/vite";
+import { fonts } from "@nubisco/ui/plugins/fonts";
+
+// src/plugins/tabs/markdown/markdownPlugin.ts
+import container from "markdown-it-container";
+
+// src/plugins/tabs/markdown/ruleBlockTab.ts
+var tabMarker = "=";
+var tabMarkerCode = tabMarker.charCodeAt(0);
+var minTabMarkerLen = 2;
+var ruleBlockTab = (state, startLine, endLine, silent) => {
+  let pos = state.bMarks[startLine] + state.tShift[startLine];
+  const max = state.eMarks[startLine];
+  if (state.parentType !== "container") {
+    return false;
+  }
+  if (pos + minTabMarkerLen > max) {
+    return false;
+  }
+  const marker = state.src.charCodeAt(pos);
+  if (marker !== tabMarkerCode) {
+    return false;
+  }
+  const mem = pos;
+  pos = state.skipChars(pos + 1, marker);
+  const tabMarkerLen = pos - mem;
+  if (tabMarkerLen < minTabMarkerLen - 1) {
+    return false;
+  }
+  if (silent) {
+    return true;
+  }
+  let nextLine = startLine;
+  let endStart = mem;
+  let endPos = pos;
+  for (; ; ) {
+    nextLine++;
+    if (nextLine >= endLine) {
+      break;
+    }
+    endStart = state.bMarks[nextLine] + state.tShift[nextLine];
+    const max2 = state.eMarks[nextLine];
+    if (endStart < max2 && state.sCount[nextLine] < state.blkIndent) {
+      break;
+    }
+    const startCharCode = state.src.charCodeAt(endStart);
+    if (startCharCode !== tabMarkerCode) {
+      continue;
+    }
+    const p = state.skipChars(endStart + 1, marker);
+    if (p - endStart !== tabMarkerLen) {
+      continue;
+    }
+    endPos = p;
+    break;
+  }
+  const oldParent = state.parentType;
+  const oldLineMax = state.lineMax;
+  state.parentType = "tab";
+  state.lineMax = nextLine;
+  const startToken = state.push("tab_open", "div", 1);
+  startToken.markup = state.src.slice(mem, pos);
+  startToken.block = true;
+  startToken.info = state.src.slice(pos, max).trimStart();
+  startToken.map = [startLine, nextLine - 1];
+  state.md.block.tokenize(state, startLine + 1, nextLine);
+  const endToken = state.push("tab_close", "div", -1);
+  endToken.markup = state.src.slice(endStart, endPos);
+  endToken.block = true;
+  state.parentType = oldParent;
+  state.lineMax = oldLineMax;
+  state.line = nextLine;
+  return true;
+};
+
+// src/plugins/tabs/markdown/markdownPlugin.ts
+var parseTabsParams = (input) => {
+  const match = input.match(/key:(\S+)/);
+  return {
+    shareStateKey: match?.[1]
+  };
+};
+var tabsPlugin = (md) => {
+  md.use(container, "tabs", {
+    render(tokens, index) {
+      const token = tokens[index];
+      if (token.nesting === 1) {
+        const params = parseTabsParams(token.info);
+        const shareStateKeyProp = params.shareStateKey ? `sharedStateKey="${md.utils.escapeHtml(params.shareStateKey)}"` : "";
+        return `<ContentTabs ${shareStateKeyProp}>
+`;
+      } else {
+        return `</ContentTabs>
+`;
+      }
+    }
+  });
+  md.block.ruler.after("container_tabs", "tab", ruleBlockTab);
+  const renderTab = (tokens, index) => {
+    const token = tokens[index];
+    if (token.nesting === 1) {
+      const label = token.info;
+      const labelProp = `label="${md.utils.escapeHtml(label)}"`;
+      return `<ContentTab ${labelProp}>
+`;
+    } else {
+      return `</ContentTab>
+`;
+    }
+  };
+  md.renderer.rules["tab_open"] = renderTab;
+  md.renderer.rules["tab_close"] = renderTab;
+};
+
+// src/plugins/mermaid/mermaid-markdown.ts
+var MermaidMarkdown = (md, pluginOptions) => {
+  const fence = md.renderer.rules.fence.bind(md.renderer.rules);
+  md.renderer.rules.fence = (tokens, index, options, env, slf) => {
+    const token = tokens[index];
+    if (token.info.trim() === "mermaid") {
+      try {
+        const key = index;
+        const cssClass = pluginOptions?.class || "mermaid";
+        return `
+      <Suspense>
+      <template #default>
+      <Mermaid id="mermaid-${key}" class="${cssClass}" graph="${encodeURIComponent(token.content)}"></Mermaid>
+      </template>
+        <!-- loading state via #fallback slot -->
+        <template #fallback>
+          Loading...
+        </template>
+      </Suspense>`;
+      } catch (err) {
+        return `<pre>${err}</pre>`;
+      }
+    }
+    if (token.info.trim() === "mmd") {
+      tokens[index].info = "mermaid";
+    }
+    return fence(tokens, index, options, env, slf);
+  };
+};
+
+// src/plugins/mermaid/mermaid-plugin.ts
+var DEFAULT_OPTIONS = {
+  // we set loose as default here because is needed to load images
+  securityLevel: "loose",
+  startOnLoad: false
+};
+function MermaidPlugin(inlineOptions) {
+  const options = {
+    ...DEFAULT_OPTIONS,
+    ...inlineOptions
+  };
+  const virtualModuleId = "virtual:mermaid-config";
+  const resolvedVirtualModuleId = "\0" + virtualModuleId;
+  return {
+    name: "vite-plugin-mermaid",
+    // The component is registered by the theme (`src/theme/index.ts`), not
+    // injected into VitePress's client entry by a path in the consumer's tree.
+    async resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+    async load(id) {
+      if (id === resolvedVirtualModuleId) {
+        return `export default ${JSON.stringify(options)};`;
+      }
+    }
+  };
+}
+
+// src/plugins/mermaid/index.ts
+var withMermaid = (config) => {
+  if (!config.markdown) config.markdown = {};
+  const markdownConfigOriginal = config.markdown.config || (() => {
+  });
+  config.markdown.config = (...args) => {
+    MermaidMarkdown(...args, config.mermaidPlugin);
+    markdownConfigOriginal(...args);
+  };
+  if (!config.vite) config.vite = {};
+  if (!config.vite.plugins) config.vite.plugins = [];
+  config.vite.plugins.push(MermaidPlugin(config.mermaid));
+  if (!config.vite.optimizeDeps) config.vite.optimizeDeps = {};
+  if (!config.vite.optimizeDeps.include) config.vite.optimizeDeps.include = [];
+  config.vite.optimizeDeps.include = [
+    ...config.vite.optimizeDeps.include,
+    "@braintree/sanitize-url",
+    "dayjs",
+    "debug",
+    "cytoscape-cose-bilkent",
+    "cytoscape"
+  ];
+  if (!config.vite.resolve) config.vite.resolve = {};
+  const mermaidPluginAlias = {
+    "dayjs/plugin/advancedFormat.js": "dayjs/esm/plugin/advancedFormat",
+    "dayjs/plugin/customParseFormat.js": "dayjs/esm/plugin/customParseFormat",
+    "dayjs/plugin/isoWeek.js": "dayjs/esm/plugin/isoWeek",
+    "cytoscape/dist/cytoscape.umd.js": "cytoscape/dist/cytoscape.esm.js"
+  };
+  if (!config.vite.resolve.alias) config.vite.resolve.alias = mermaidPluginAlias;
+  else if (Array.isArray(config.vite.resolve.alias)) {
+    config.vite.resolve.alias = [
+      ...config.vite.resolve.alias,
+      ...Object.entries(mermaidPluginAlias).map(([find, replacement]) => ({
+        find,
+        replacement
+      }))
+    ];
+  } else {
+    config.vite.resolve.alias = {
+      ...config.vite.resolve.alias,
+      ...mermaidPluginAlias
+    };
+  }
+  return config;
+};
+
+// src/node/index.ts
+var ANALYTICS = "https://analytics.nubisco.io/script.js";
+function defineNubiscoDocs(options) {
+  const base = options.base;
+  const logo = options.logo ?? "/logo.svg";
+  const extra = options.vitepress ?? {};
+  const analytics = options.analytics ?? ANALYTICS;
+  const docsDir = options.docsDir ?? "docs/";
+  const branch = options.branch ?? "master";
+  const config = defineConfig({
+    ...extra,
+    title: options.title,
+    description: options.description,
+    base,
+    // The theme owns light and dark (`useTheme()` sets `.dark`), so VitePress's
+    // own appearance switch stays off.
+    appearance: false,
+    // `_shared.md` fragments are included by tab pages. They are not pages.
+    srcExclude: ["**/_*.md", ...extra.srcExclude ?? []],
+    lastUpdated: true,
+    head: [
+      ["link", { rel: "icon", href: `${base}favicon.ico`, sizes: "any" }],
+      [
+        "link",
+        {
+          rel: "icon",
+          type: "image/png",
+          sizes: "32x32",
+          href: `${base}favicon-32x32.png`
+        }
+      ],
+      [
+        "link",
+        {
+          rel: "icon",
+          type: "image/png",
+          sizes: "16x16",
+          href: `${base}favicon-16x16.png`
+        }
+      ],
+      [
+        "link",
+        {
+          rel: "apple-touch-icon",
+          sizes: "180x180",
+          href: `${base}apple-touch-icon.png`
+        }
+      ],
+      ["link", { rel: "manifest", href: `${base}site.webmanifest` }],
+      [
+        "meta",
+        { name: "theme-color", content: options.themeColor ?? "#0d0d0f" }
+      ],
+      ...analytics ? [
+        ["script", { defer: "", src: analytics }]
+      ] : [],
+      ...extra.head ?? []
+    ],
+    markdown: {
+      ...extra.markdown,
+      config(md) {
+        md.use(tabsPlugin);
+        md.use(groupIconMdPlugin);
+        extra.markdown?.config?.(md);
+      }
+    },
+    sitemap: { hostname: options.hostname, ...extra.sitemap },
+    vite: {
+      ...extra.vite,
+      plugins: [
+        svgLoader(),
+        groupIconVitePlugin(),
+        // The theme passes icon modules to NbIcon at run time, which the glyph
+        // transform cannot see through. They need no catalogue.
+        nubiscoUI({ glyphs: { catalog: "off", warnUnresolved: false } }),
+        fonts(),
+        ...extra.vite?.plugins ?? []
+      ],
+      ssr: {
+        ...extra.vite?.ssr,
+        // The theme and the library ship Vue sources and ESM, which VitePress
+        // must compile with the page, not load from node_modules as is.
+        noExternal: [
+          "@nubisco/docs-sdk",
+          "@nubisco/ui",
+          "vue",
+          ...extra.vite?.ssr?.noExternal ?? []
+        ]
+      },
+      optimizeDeps: {
+        ...extra.vite?.optimizeDeps,
+        exclude: [
+          "@nubisco/docs-sdk",
+          ...extra.vite?.optimizeDeps?.exclude ?? []
+        ]
+      },
+      css: {
+        ...extra.vite?.css,
+        preprocessorOptions: {
+          scss: { api: "modern-compiler" },
+          ...extra.vite?.css?.preprocessorOptions
+        }
+      }
+    },
+    themeConfig: {
+      siteTitle: options.title,
+      logo: { src: logo, width: 24, height: 24 },
+      nav: options.nav,
+      sidebar: options.sidebar,
+      socialLinks: [
+        { icon: "github", link: `https://github.com/${options.repo}` }
+      ],
+      editLink: {
+        pattern: `https://github.com/${options.repo}/edit/${branch}/${docsDir}:path`,
+        text: "Edit this page on GitHub"
+      },
+      search: { provider: "local" },
+      lastUpdated: { text: "Last updated" },
+      footer: options.footer,
+      ...extra.themeConfig,
+      // Read by the theme. Typed in `INubiscoDocsThemeConfig`.
+      nubisco: {
+        repo: options.repo,
+        branch,
+        appearanceControl: options.appearanceControl ?? false
+      }
+    }
+  });
+  return withMermaid(config);
+}
+export {
+  defineNubiscoDocs
+};