@octanejs/docusaurus 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dominic Gannaway
+
+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

@@ -0,0 +1,100 @@
+# `@octanejs/docusaurus`
+
+The headless Docusaurus content and MDX bridge for Octane.
+
+Docusaurus has a useful boundary before React: its Node-side config, presets,
+and plugins load content, create data modules, and emit a serializable route
+tree. This package adopts that graph, normalizes it into a renderer-neutral
+manifest, resolves Docusaurus module aliases for Vite, and compiles
+Docusaurus-shaped MDX exports into real Octane components.
+
+It does **not** run React themes or React-authored swizzles unchanged. Octane is
+compiler-first; the renderer and theme layers must be authored for Octane.
+
+## Version contract
+
+The headless loader is intentionally pinned to `@docusaurus/core@3.10.1`.
+Docusaurus does not publish the `server/site` loader as a stable public entry,
+so accepting an untested minor would turn an internal upstream refactor into a
+silent route-data corruption. The loader checks both the package version and
+Docusaurus's Node `>=20.0` runtime requirement before importing that seam. This
+package retains Octane's repository-wide Node `>=22` baseline.
+
+`allowUnsupportedVersion: true` is available only for explicit compatibility
+experiments.
+
+## Inspect the headless site graph
+
+```js
+import {
+	createDocusaurusManifest,
+	loadDocusaurusSite,
+} from '@octanejs/docusaurus';
+
+const loaded = await loadDocusaurusSite({ siteDir: process.cwd() });
+const manifest = await createDocusaurusManifest(loaded);
+```
+
+The manifest contains:
+
+- nested routes with `component`, `modules`, `props`, and plugin context;
+- generated global data and per-document metadata;
+- `@site`, `@generated`, `~docs`, `@theme`, `@theme-original`, and
+  `@theme-init` resolution;
+- the exact Docusaurus version and route-path inventory.
+
+The CLI exposes the same boundary:
+
+```bash
+octane-docusaurus inspect --site-dir . --out .octane-docusaurus/manifest.json
+octane-docusaurus clear --site-dir .
+```
+
+## Vite
+
+```ts
+import { defineConfig } from 'vite';
+import { octane } from 'octane/compiler/vite';
+import { docusaurus } from '@octanejs/docusaurus/vite';
+
+export default defineConfig({
+	plugins: [...docusaurus(), octane()],
+});
+```
+
+The bridge publishes `virtual:octane-docusaurus-manifest` and resolves
+Docusaurus aliases. Its MDX plugin chooses Octane client/server compilation per
+Vite environment and injects metadata discovered by the content plugins.
+
+## Docusaurus-aware MDX
+
+```js
+import { compileDocusaurusMdx } from '@octanejs/docusaurus/mdx';
+
+const result = await compileDocusaurusMdx(source, '/docs/intro.mdx', {
+	metadata: docMetadata,
+	resolveMarkdownLink: ({ linkPathname }) =>
+		linkPathname.startsWith('./') ? `/guide/${linkPathname.slice(2)}` : null,
+});
+```
+
+Alongside the default document component, compiled modules export Docusaurus's
+document shape:
+
+- `frontMatter` (plus `@octanejs/mdx`'s existing `frontmatter`);
+- `contentTitle`;
+- `toc`;
+- `metadata`;
+- `assets`.
+
+GitHub-compatible heading IDs (including explicit Docusaurus IDs), duplicate
+slugs, first-title wrapping/removal, TOC bounds, and Markdown link/image
+rewriting happen before Octane compilation. User remark/rehype/recma plugins
+remain composable.
+
+## Current scope
+
+Phases 1–3 are implemented here: headless loading, manifest/Vite integration,
+and MDX compilation. Client routing, static generation, hydration, and an
+Octane classic theme are deliberately left to the renderer/theme phases; the
+CLI therefore does not present `start` or `build` as working commands yet.

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@octanejs/docusaurus",
+  "version": "0.0.1",
+  "description": "Docusaurus content and MDX integration for Octane",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/docusaurus"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "octane-docusaurus": "src/bin.js"
+  },
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./mdx": {
+      "types": "./types/mdx.d.ts",
+      "import": "./src/mdx.js",
+      "default": "./src/mdx.js"
+    },
+    "./vite": {
+      "types": "./types/vite.d.ts",
+      "import": "./src/vite.js",
+      "default": "./src/vite.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "github-slugger": "1.5.0",
+    "@octanejs/mdx": "0.1.14"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": "3.10.1",
+    "vite": ">=7.0.0",
+    "octane": "0.1.17"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@docusaurus/core": "3.10.1",
+    "@docusaurus/plugin-content-docs": "3.10.1",
+    "@types/node": "^24.13.3",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10",
+    "octane": "0.1.17"
+  },
+  "scripts": {
+    "test": "cd ../.. && vitest run --project docusaurus"
+  }
+}

package/src/bin.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { rm } from 'node:fs/promises';
+import path from 'node:path';
+import { createDocusaurusManifest, loadDocusaurusSite, writeDocusaurusManifest } from './index.js';
+
+function usage() {
+	return `Usage:
+  octane-docusaurus inspect [--site-dir DIR] [--config FILE] [--locale LOCALE] [--out FILE]
+  octane-docusaurus clear [--site-dir DIR]
+
+The phase 1-3 command inspects Docusaurus's headless route/data graph. Static
+site build, hydration, and theme commands arrive with the renderer phases.
+`;
+}
+
+function parseArguments(argv) {
+	const command = argv[0];
+	const options = {};
+	for (let index = 1; index < argv.length; index++) {
+		const argument = argv[index];
+		if (argument === '--allow-unsupported-version') {
+			options.allowUnsupportedVersion = true;
+			continue;
+		}
+		if (!argument.startsWith('--')) throw new Error(`Unexpected argument: ${argument}`);
+		const value = argv[++index];
+		if (value === undefined) throw new Error(`Missing value for ${argument}`);
+		if (argument === '--site-dir') options.siteDir = value;
+		else if (argument === '--config') options.config = value;
+		else if (argument === '--locale') options.locale = value;
+		else if (argument === '--out') options.out = value;
+		else throw new Error(`Unknown option: ${argument}`);
+	}
+	return { command, options };
+}
+
+async function inspect(options) {
+	const loaded = await loadDocusaurusSite(options);
+	const manifest = await createDocusaurusManifest(loaded);
+	if (options.out) {
+		const filename = await writeDocusaurusManifest(manifest, options.out);
+		process.stdout.write(`${filename}\n`);
+	} else {
+		process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+	}
+}
+
+async function clear(options) {
+	const siteDir = path.resolve(options.siteDir ?? process.cwd());
+	await Promise.all([
+		rm(path.join(siteDir, '.docusaurus'), { recursive: true, force: true }),
+		rm(path.join(siteDir, '.octane-docusaurus'), { recursive: true, force: true }),
+	]);
+}
+
+async function main() {
+	const { command, options } = parseArguments(process.argv.slice(2));
+	if (command === 'inspect') await inspect(options);
+	else if (command === 'clear') await clear(options);
+	else {
+		process.stderr.write(usage());
+		process.exitCode = command === '--help' || command === '-h' ? 0 : 2;
+	}
+}
+
+main().catch((error) => {
+	process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+	process.exitCode = 1;
+});

package/src/index.js

@@ -0,0 +1,13 @@
+export {
+	MINIMUM_DOCUSARUS_NODE_VERSION,
+	SUPPORTED_DOCUSARUS_VERSION,
+	assertSupportedDocusaurusRuntime,
+	resolveDocusaurusCore,
+} from './version.js';
+export { loadDocusaurusSite } from './load-site.js';
+export {
+	createDocusaurusManifest,
+	readDocusaurusManifest,
+	resolveDocusaurusId,
+	writeDocusaurusManifest,
+} from './manifest.js';

package/src/load-site.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assertSupportedDocusaurusRuntime, resolveDocusaurusCore } from './version.js';
+
+export async function loadDocusaurusSite(options = {}) {
+	const siteDir = path.resolve(options.siteDir ?? process.cwd());
+	const core = await resolveDocusaurusCore(siteDir);
+	assertSupportedDocusaurusRuntime(core, options);
+
+	const siteModuleUrl = pathToFileURL(path.join(core.packageRoot, 'lib/server/site.js')).href;
+	const siteModule = await import(siteModuleUrl);
+	if (typeof siteModule.loadSite !== 'function') {
+		throw new Error(
+			`[@octanejs/docusaurus] @docusaurus/core@${core.version} no longer exposes the ` +
+				'internal server/site loadSite() seam.',
+		);
+	}
+
+	const site = await siteModule.loadSite({
+		siteDir,
+		...(options.outDir === undefined ? {} : { outDir: options.outDir }),
+		...(options.config === undefined ? {} : { config: options.config }),
+		...(options.locale === undefined ? {} : { locale: options.locale }),
+		...(options.automaticBaseUrlLocalizationDisabled === undefined
+			? {}
+			: {
+					automaticBaseUrlLocalizationDisabled: options.automaticBaseUrlLocalizationDisabled,
+				}),
+	});
+
+	return {
+		corePath: core.packageRoot,
+		docusaurusVersion: core.version,
+		site,
+	};
+}

package/src/manifest.js

@@ -0,0 +1,261 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const SOURCE_EXTENSIONS = ['.tsrx', '.tsx', '.jsx', '.ts', '.js', '.mjs', '.cjs'];
+const RESOLVE_EXTENSIONS = [...SOURCE_EXTENSIONS, '.json', '.mdx', '.md', '.css'];
+
+function toJsonValue(value, trail = '$', active = new WeakSet()) {
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'number' ||
+		typeof value === 'boolean'
+	) {
+		return value;
+	}
+	if (value === undefined) return undefined;
+	if (typeof value === 'bigint' || typeof value === 'symbol' || typeof value === 'function') {
+		throw new TypeError(`${trail} is not serializable in a Docusaurus route manifest.`);
+	}
+	if (active.has(value)) {
+		throw new TypeError(`${trail} is cyclic and cannot be serialized.`);
+	}
+	active.add(value);
+	let result;
+	if (Array.isArray(value)) {
+		result = value.map((item, index) => toJsonValue(item, `${trail}[${index}]`, active));
+	} else {
+		result = {};
+		for (const [key, item] of Object.entries(value)) {
+			const serialized = toJsonValue(item, `${trail}.${key}`, active);
+			if (serialized !== undefined) result[key] = serialized;
+		}
+	}
+	active.delete(value);
+	return result;
+}
+
+function moduleId(module) {
+	if (typeof module === 'string') return module;
+	if (module && typeof module === 'object' && module.__import === true) {
+		return {
+			__import: true,
+			path: String(module.path),
+			...(module.query === undefined ? {} : { query: toJsonValue(module.query) }),
+		};
+	}
+	throw new TypeError(`Expected a Docusaurus module reference, received ${String(module)}.`);
+}
+
+function normalizeRoute(route, index, parentId = 'root') {
+	const id = `${parentId}/${index}:${route.path}`;
+	const modules = {};
+	for (const [name, value] of Object.entries(route.modules ?? {})) {
+		modules[name] = Array.isArray(value) ? value.map(moduleId) : moduleId(value);
+	}
+	const known = new Set([
+		'path',
+		'component',
+		'modules',
+		'context',
+		'props',
+		'routes',
+		'exact',
+		'priority',
+		'metadata',
+		'plugin',
+	]);
+	const attributes = {};
+	for (const [name, value] of Object.entries(route)) {
+		if (known.has(name)) continue;
+		const serialized = toJsonValue(value, `route(${route.path}).${name}`);
+		if (serialized !== undefined) attributes[name] = serialized;
+	}
+	return {
+		id,
+		path: String(route.path),
+		component: moduleId(route.component),
+		exact: route.exact === true,
+		...(route.priority === undefined ? {} : { priority: Number(route.priority) }),
+		...(Object.keys(modules).length === 0 ? {} : { modules }),
+		...(route.context === undefined
+			? {}
+			: { context: toJsonValue(route.context, `route(${route.path}).context`) }),
+		...(route.props === undefined
+			? {}
+			: { props: toJsonValue(route.props, `route(${route.path}).props`) }),
+		...(route.metadata === undefined
+			? {}
+			: { metadata: toJsonValue(route.metadata, `route(${route.path}).metadata`) }),
+		...(route.plugin === undefined
+			? {}
+			: { plugin: toJsonValue(route.plugin, `route(${route.path}).plugin`) }),
+		...(Object.keys(attributes).length === 0 ? {} : { attributes }),
+		children: (route.routes ?? []).map((child, childIndex) =>
+			normalizeRoute(child, childIndex, id),
+		),
+	};
+}
+
+function listFiles(directory) {
+	if (!existsSync(directory)) return [];
+	return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+		const absolute = path.join(directory, entry.name);
+		return entry.isDirectory() ? listFiles(absolute) : [absolute];
+	});
+}
+
+function themeKey(file, root) {
+	const relative = path.relative(root, file).split(path.sep).join('/');
+	if (relative.endsWith('.d.ts')) return null;
+	const extension = SOURCE_EXTENSIONS.find((candidate) => relative.endsWith(candidate));
+	if (!extension) return null;
+	let key = relative.slice(0, -extension.length);
+	if (key.endsWith('/index')) key = key.slice(0, -'/index'.length);
+	return key;
+}
+
+async function themeLayers(plugins) {
+	const layers = [];
+	for (const plugin of plugins) {
+		if (typeof plugin.getThemePath !== 'function') continue;
+		const supplied = await plugin.getThemePath();
+		if (typeof supplied !== 'string') continue;
+		layers.push(path.isAbsolute(supplied) ? supplied : path.resolve(plugin.path, supplied));
+	}
+	return layers;
+}
+
+async function createThemeAliases(plugins, siteDir) {
+	const providers = new Map();
+	for (const root of await themeLayers(plugins)) {
+		for (const file of listFiles(root)) {
+			const key = themeKey(file, root);
+			if (key === null) continue;
+			const entries = providers.get(key) ?? [];
+			entries.push(file);
+			providers.set(key, entries);
+		}
+	}
+	const theme = {};
+	const themeOriginal = {};
+	const themeInit = {};
+	for (const [key, entries] of providers) {
+		theme[key] = entries.at(-1);
+		themeOriginal[key] = entries.at(-1);
+		if (entries.length > 1) themeInit[key] = entries[0];
+	}
+	const siteTheme = path.join(siteDir, 'src/theme');
+	for (const file of listFiles(siteTheme)) {
+		const key = themeKey(file, siteTheme);
+		if (key !== null) theme[key] = file;
+	}
+	return { theme, themeOriginal, themeInit };
+}
+
+function readJsonIfPresent(filename, fallback) {
+	if (!existsSync(filename)) return fallback;
+	return JSON.parse(readFileSync(filename, 'utf8'));
+}
+
+function contentMetadata(generatedFilesDir) {
+	const roots = [
+		path.join(generatedFilesDir, 'docusaurus-plugin-content-docs'),
+		path.join(generatedFilesDir, 'docusaurus-plugin-content-pages'),
+	];
+	const content = {};
+	for (const root of roots) {
+		for (const file of listFiles(root)) {
+			if (!file.endsWith('.json') || path.basename(file).startsWith('__')) continue;
+			let value;
+			try {
+				value = JSON.parse(readFileSync(file, 'utf8'));
+			} catch {
+				continue;
+			}
+			if (value && typeof value === 'object' && typeof value.source === 'string') {
+				content[value.source] = value;
+			}
+		}
+	}
+	return content;
+}
+
+export async function createDocusaurusManifest(loaded) {
+	const { props } = loaded.site;
+	const { siteDir, generatedFilesDir } = props;
+	const themeAliases = await createThemeAliases(props.plugins ?? [], siteDir);
+	return {
+		schemaVersion: 1,
+		docusaurusVersion: loaded.docusaurusVersion,
+		siteDir,
+		generatedFilesDir,
+		outDir: props.outDir,
+		baseUrl: props.baseUrl,
+		routesPaths: [...props.routesPaths],
+		routes: props.routes.map((route, index) => normalizeRoute(route, index)),
+		globalData: readJsonIfPresent(path.join(generatedFilesDir, 'globalData.json'), {}),
+		content: contentMetadata(generatedFilesDir),
+		aliases: {
+			site: siteDir,
+			generated: generatedFilesDir,
+			docs: path.join(generatedFilesDir, 'docusaurus-plugin-content-docs'),
+			...themeAliases,
+		},
+	};
+}
+
+function resolvedFile(candidate) {
+	if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+	for (const extension of RESOLVE_EXTENSIONS) {
+		const filename = candidate + extension;
+		if (existsSync(filename) && statSync(filename).isFile()) return filename;
+	}
+	if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+		for (const extension of RESOLVE_EXTENSIONS) {
+			const filename = path.join(candidate, `index${extension}`);
+			if (existsSync(filename) && statSync(filename).isFile()) return filename;
+		}
+	}
+	return null;
+}
+
+function within(root, relativeId) {
+	const candidate = path.resolve(root, relativeId);
+	const relative = path.relative(root, candidate);
+	if (relative.startsWith('..') || path.isAbsolute(relative)) return null;
+	return resolvedFile(candidate);
+}
+
+export function resolveDocusaurusId(id, manifest) {
+	const queryIndex = id.indexOf('?');
+	const source = queryIndex === -1 ? id : id.slice(0, queryIndex);
+	const query = queryIndex === -1 ? '' : id.slice(queryIndex);
+	let resolved = null;
+	if (source.startsWith('@site/')) {
+		resolved = within(manifest.aliases.site, source.slice('@site/'.length));
+	} else if (source.startsWith('@generated/')) {
+		resolved = within(manifest.aliases.generated, source.slice('@generated/'.length));
+	} else if (source.startsWith('~docs/')) {
+		resolved = within(manifest.aliases.docs, source.slice('~docs/'.length));
+	} else if (source.startsWith('@theme-original/')) {
+		resolved = manifest.aliases.themeOriginal[source.slice('@theme-original/'.length)] ?? null;
+	} else if (source.startsWith('@theme-init/')) {
+		resolved = manifest.aliases.themeInit[source.slice('@theme-init/'.length)] ?? null;
+	} else if (source.startsWith('@theme/')) {
+		resolved = manifest.aliases.theme[source.slice('@theme/'.length)] ?? null;
+	}
+	return resolved === null ? null : resolved + query;
+}
+
+export async function writeDocusaurusManifest(manifest, filename) {
+	const target = path.resolve(filename);
+	await mkdir(path.dirname(target), { recursive: true });
+	await writeFile(target, `${JSON.stringify(manifest, null, 2)}\n`);
+	return target;
+}
+
+export async function readDocusaurusManifest(filename) {
+	return JSON.parse(await readFile(filename, 'utf8'));
+}