@vantagecompute/docusaurus-theme 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# @vantagecompute/docusaurus-theme
+
+Shared Docusaurus theme for all Vantage Compute documentation sites. Provides the Vantage design system (CSS tokens, typography, dark/light themes), brand assets (Satoshi fonts, SVG icons, logo), and common theme component overrides.
+
+## Installation
+
+```bash
+npm install @vantagecompute/docusaurus-theme
+```
+
+## Usage
+
+Add the theme to your `docusaurus.config.js`:
+
+```js
+const { staticDir, rehypeTabsTransform } = require('@vantagecompute/docusaurus-theme');
+
+const config = {
+  // Add the Vantage theme
+  themes: ['@vantagecompute/docusaurus-theme'],
+
+  // Serve shared static assets (fonts, icons, logo)
+  staticDirectories: ['static', staticDir],
+
+  presets: [
+    ['classic', {
+      docs: {
+        // Optional: use the shared rehype plugin for lowercase <tabs>/<tabitem> support
+        rehypePlugins: [rehypeTabsTransform],
+      },
+      // Do NOT set customCss — the theme injects it automatically
+    }],
+  ],
+};
+```
+
+## What's included
+
+### Design System CSS
+The full Vantage design system (`custom.css`) is automatically loaded as a client module. It provides:
+- **Design tokens** — Ink (neutral) and Iris (accent) color palettes with CSS variables
+- **Dark/light themes** — Complete dark mode support
+- **Typography** — Satoshi + Open Sans body, JetBrains Mono code
+- **Component styles** — Navbar, sidebar, TOC, admonitions/callouts, tables, code blocks, breadcrumbs, tabs, guided how-to steps, and more
+
+### Brand Assets (static files)
+Served automatically via `configureStaticDirs`:
+- **Fonts** — Satoshi (Regular, Medium, Bold + italics) as `.woff` files
+- **Icons** — Sun/moon toggles, search, external link, GitHub, chevron SVGs
+- **Logo** — `vantage-logo.svg`
+- **Favicon** — `favicon.ico`
+
+### Theme Component Overrides
+| Component | Description |
+|---|---|
+| `ColorModeToggle` | Custom sun/moon SVG icon toggle |
+| `DocBreadcrumbs` | Full-path breadcrumb rendering |
+| `Tabs` | Bugfix for Docusaurus 3.10 whitespace crash |
+| `MDXComponents` | Global `Tabs`/`TabItem` registration |
+| `Navbar/MobileSidebar/SecondaryMenu` | Clean secondary menu render |
+
+### Utilities
+| Export | Description |
+|---|---|
+| `rehypeTabsTransform` | Rehype plugin that transforms lowercase `<tabs>`/`<tabitem>` to React components |
+
+## Customization
+
+### Overriding theme components
+Docusaurus uses layered theme resolution. To override any component the shared theme provides, create the same file path in your site's `src/theme/` directory. Your local version takes priority.
+
+```
+your-docs-site/
+  src/
+    theme/
+      ColorModeToggle/     ← overrides the package's ColorModeToggle
+        index.js
+```
+
+### 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:
+
+```js
+presets: [
+  ['classic', {
+    theme: {
+      customCss: require.resolve('./src/css/custom.css'),
+    },
+  }],
+],
+```
+
+### Overriding CSS variables
+Override any design token in your custom CSS:
+
+```css
+:root {
+  --iris-700: #your-brand-color;
+  --ifm-color-primary: #your-brand-color;
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run build    # Compile TypeScript entry point
+```
+
+The package uses TypeScript for the plugin entry point (`src/index.ts` → `lib/index.js`). Theme components, CSS, and static assets are shipped as source and resolved by Docusaurus at build time.
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,16 @@
+import type { Plugin } from '@docusaurus/types';
+export default function themeVantage(): Plugin;
+/**
+ * Returns the absolute path to this package's static directory.
+ * Add this to your `staticDirectories` in docusaurus.config.js:
+ *
+ * ```js
+ * const { staticDir } = require('@vantagecompute/docusaurus-theme');
+ * module.exports = {
+ *   staticDirectories: ['static', staticDir],
+ * };
+ * ```
+ */
+export declare const staticDir: string;
+export { default as rehypeTabsTransform } from './utils/rehypeTabsTransform';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,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,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,6BAA6B,CAAC"}

package/lib/index.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rehypeTabsTransform = exports.staticDir = void 0;
+exports.default = themeVantage;
+const path_1 = __importDefault(require("path"));
+function themeVantage() {
+    return {
+        name: '@vantagecompute/docusaurus-theme',
+        getThemePath() {
+            return path_1.default.resolve(__dirname, '../src/theme');
+        },
+        getPathsToWatch() {
+            return [path_1.default.resolve(__dirname, '../src/theme/**/*.{js,jsx,ts,tsx,css}')];
+        },
+        getClientModules() {
+            return [path_1.default.resolve(__dirname, '../src/css/custom.css')];
+        },
+    };
+}
+/**
+ * Returns the absolute path to this package's static directory.
+ * Add this to your `staticDirectories` in docusaurus.config.js:
+ *
+ * ```js
+ * const { staticDir } = require('@vantagecompute/docusaurus-theme');
+ * module.exports = {
+ *   staticDirectories: ['static', staticDir],
+ * };
+ * ```
+ */
+exports.staticDir = path_1.default.resolve(__dirname, '../static');
+var rehypeTabsTransform_1 = require("./utils/rehypeTabsTransform");
+Object.defineProperty(exports, "rehypeTabsTransform", { enumerable: true, get: function () { return __importDefault(rehypeTabsTransform_1).default; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAGA,+BAgBC;AAnBD,gDAAwB;AAGxB,SAAwB,YAAY;IAClC,OAAO;QACL,IAAI,EAAE,kCAAkC;QAExC,YAAY;YACV,OAAO,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QACjD,CAAC;QAED,eAAe;YACb,OAAO,CAAC,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,uCAAuC,CAAC,CAAC,CAAC;QAC5E,CAAC;QAED,gBAAgB;YACd,OAAO,CAAC,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC,CAAC;QAC5D,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACU,QAAA,SAAS,GAAG,cAAI,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAE9D,mEAA6E;AAApE,2IAAA,OAAO,OAAuB"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@vantagecompute/docusaurus-theme",
+  "version": "0.1.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.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "static",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": "^3.0.0",
+    "@docusaurus/theme-common": "^3.0.0",
+    "@docusaurus/plugin-content-docs": "^3.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "dependencies": {
+    "clsx": "^2.0.0",
+    "unist-util-visit": "^5.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^3.10.1",
+    "@docusaurus/tsconfig": "^3.10.1",
+    "@docusaurus/types": "^3.10.1",
+    "@types/react": "^19.2.17",
+    "typescript": "~5.6.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vantagecompute/vantage-docusaurus-theme.git"
+  },
+  "keywords": [
+    "docusaurus",
+    "docusaurus-theme",
+    "vantage",
+    "vantagecompute",
+    "documentation"
+  ]
+}