@octanejs/docusaurus 0.0.1

package/src/mdx.js

@@ -0,0 +1,319 @@
+import { compileMdx, compileMdxSync, defaultRemarkPlugins } from '@octanejs/mdx/compile';
+import GithubSlugger from 'github-slugger';
+
+const DATA_KEY = 'octaneDocusaurus';
+
+function walk(node, visit) {
+	if (!node || typeof node !== 'object') return;
+	visit(node);
+	for (const [key, value] of Object.entries(node)) {
+		if (key === 'position' || key === 'data') continue;
+		if (Array.isArray(value)) {
+			for (const child of value) walk(child, visit);
+		} else {
+			walk(value, visit);
+		}
+	}
+}
+
+function textContent(node) {
+	let text = '';
+	walk(node, (child) => {
+		if (child === node) return;
+		if (child.type === 'text' || child.type === 'inlineCode') text += child.value ?? '';
+		if (child.type === 'image') text += child.alt ?? '';
+	});
+	return text.trim();
+}
+
+function createSlugger(maintainCase) {
+	const slugger = new GithubSlugger();
+	return {
+		explicit(value) {
+			return slugger.slug(value, true);
+		},
+		generated(value) {
+			return slugger.slug(value, maintainCase);
+		},
+	};
+}
+
+function transformImageUrl(transform, url, sourceFilePath) {
+	if (typeof transform !== 'function') return url;
+	const transformed = transform({ url, sourceFilePath });
+	if (typeof transformed !== 'string') {
+		throw new TypeError('A Docusaurus MDX image transform must return a string.');
+	}
+	return transformed;
+}
+
+function transformMarkdownLink(transform, url, sourceFilePath) {
+	if (typeof transform !== 'function') return url;
+	if (/^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(url)) return url;
+	const match = /^([^?#]*)(.*)$/.exec(url);
+	const linkPathname = match?.[1] ?? url;
+	if (!/\.mdx?$/i.test(linkPathname)) return url;
+	const transformed = transform({ linkPathname, sourceFilePath });
+	if (transformed === null) return url;
+	if (typeof transformed !== 'string') {
+		throw new TypeError('A Docusaurus Markdown link resolver must return a string or null.');
+	}
+	return transformed + (match?.[2] ?? '');
+}
+
+function classicHeadingId(heading, headingText) {
+	const match = /\s*\{#((?:.(?!\{#|\}))*.)\}$/.exec(headingText);
+	if (!match) return undefined;
+	const id = match[1].trim();
+	const last = heading.children?.at(-1);
+	if (last?.type === 'text') {
+		last.value = String(last.value).replace(/\s*\{#(?:.(?!\{#|\}))*.\}$/, '');
+		if (!last.value && heading.children.length > 1) heading.children.pop();
+	}
+	return id;
+}
+
+function commentHeadingId(heading) {
+	const last = heading.children?.at(-1);
+	if (last?.type !== 'mdxTextExpression' || !last.data?.estree) return undefined;
+	const program = last.data.estree;
+	if (program.body?.length !== 0 || program.comments?.length !== 1) return undefined;
+	const first = String(program.comments[0].value).trim().split(' ')[0];
+	if (!first?.startsWith('#') || first.length === 1) return undefined;
+	heading.children.pop();
+	const newLast = heading.children.at(-1);
+	if (newLast?.type === 'text') newLast.value = newLast.value.trimEnd();
+	return first.slice(1);
+}
+
+function headingId(node, headingText, slugger) {
+	const existing = node.data?.hProperties?.id;
+	if (typeof existing === 'string' && existing) return slugger.explicit(existing);
+	return (
+		commentHeadingId(node) ?? classicHeadingId(node, headingText) ?? slugger.generated(headingText)
+	);
+}
+
+export function remarkDocusaurusPageData(options = {}) {
+	return (tree, file) => {
+		const slugger = createSlugger(options.anchorsMaintainCase === true);
+		const toc = [];
+		let contentTitle;
+		let titleIndex = -1;
+		let contentTitleCandidate = true;
+		const children = Array.isArray(tree.children) ? tree.children : [];
+
+		for (let index = 0; index < children.length; index++) {
+			const node = children[index];
+			if (node.type === 'heading') {
+				const originalValue = textContent(node);
+				node.data ??= {};
+				node.data.hProperties ??= {};
+				const id = headingId(node, originalValue, slugger);
+				node.data.hProperties.id = id;
+				node.data.id = id;
+				const value = textContent(node);
+				if (contentTitleCandidate && node.depth === 1) {
+					contentTitle = value;
+					titleIndex = index;
+					contentTitleCandidate = false;
+				} else if (contentTitleCandidate) {
+					contentTitleCandidate = false;
+				}
+				if (
+					node.depth >= (options.tocMinHeadingLevel ?? 2) &&
+					node.depth <= (options.tocMaxHeadingLevel ?? 3)
+				) {
+					toc.push({ value, id, level: node.depth });
+				}
+			}
+			if (node.type === 'thematicBreak') contentTitleCandidate = false;
+		}
+
+		const sourceFilePath = String(file.path ?? '');
+		walk(tree, (node) => {
+			if ((node.type === 'link' || node.type === 'definition') && typeof node.url === 'string') {
+				node.url = transformMarkdownLink(options.resolveMarkdownLink, node.url, sourceFilePath);
+			}
+			if (node.type === 'image' && typeof node.url === 'string') {
+				node.url = transformImageUrl(options.resolveMarkdownImage, node.url, sourceFilePath);
+			}
+		});
+
+		if (titleIndex !== -1) {
+			if (options.removeContentTitle === true) {
+				children.splice(titleIndex, 1);
+			} else {
+				children[titleIndex] = {
+					type: 'mdxJsxFlowElement',
+					name: 'header',
+					attributes: [],
+					children: [children[titleIndex]],
+				};
+			}
+		}
+		file.data[DATA_KEY] = {
+			toc,
+			contentTitle,
+			metadata: options.metadata ?? {},
+			assets:
+				typeof options.createAssets === 'function'
+					? options.createAssets({
+							frontMatter: options.metadata?.frontMatter ?? {},
+							filePath: sourceFilePath,
+						})
+					: {},
+		};
+	};
+}
+
+function literal(value) {
+	if (value === undefined) {
+		return { type: 'Identifier', name: 'undefined' };
+	}
+	if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+		return { type: 'Literal', value };
+	}
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value)) {
+			throw new TypeError('Docusaurus MDX exports must contain finite numbers.');
+		}
+		return { type: 'Literal', value };
+	}
+	if (Array.isArray(value)) {
+		return { type: 'ArrayExpression', elements: value.map(literal) };
+	}
+	if (value && typeof value === 'object') {
+		return {
+			type: 'ObjectExpression',
+			properties: Object.entries(value)
+				.filter(([, item]) => item !== undefined)
+				.map(([key, item]) => ({
+					type: 'Property',
+					method: false,
+					shorthand: false,
+					computed: false,
+					kind: 'init',
+					key: /^[A-Za-z_$][\w$]*$/.test(key)
+						? { type: 'Identifier', name: key }
+						: { type: 'Literal', value: key },
+					value: literal(item),
+				})),
+		};
+	}
+	throw new TypeError(`Docusaurus MDX export value ${String(value)} is not serializable.`);
+}
+
+function exportedConstant(name, expression) {
+	return {
+		type: 'ExportNamedDeclaration',
+		declaration: {
+			type: 'VariableDeclaration',
+			kind: 'const',
+			declarations: [
+				{
+					type: 'VariableDeclarator',
+					id: { type: 'Identifier', name },
+					init: expression,
+				},
+			],
+		},
+		specifiers: [],
+		source: null,
+	};
+}
+
+export function recmaDocusaurusPageExports() {
+	return (tree, file) => {
+		const data = file.data[DATA_KEY] ?? {
+			toc: [],
+			contentTitle: undefined,
+			metadata: {},
+			assets: {},
+		};
+		tree.body.push(
+			exportedConstant('frontMatter', { type: 'Identifier', name: 'frontmatter' }),
+			exportedConstant('contentTitle', literal(data.contentTitle)),
+			exportedConstant('toc', literal(data.toc)),
+			exportedConstant('metadata', literal(data.metadata)),
+			exportedConstant('assets', literal(data.assets)),
+		);
+	};
+}
+
+function compileOptions(options) {
+	const {
+		beforeDefaultRemarkPlugins = [],
+		remarkPlugins = [],
+		beforeDefaultRehypePlugins = [],
+		rehypePlugins = [],
+		recmaPlugins = [],
+		metadata,
+		createAssets,
+		resolveMarkdownLink,
+		resolveMarkdownImage,
+		removeContentTitle,
+		anchorsMaintainCase,
+		tocMinHeadingLevel,
+		tocMaxHeadingLevel,
+		...base
+	} = options;
+	const pageDataOptions = {
+		metadata,
+		createAssets,
+		resolveMarkdownLink,
+		resolveMarkdownImage,
+		removeContentTitle,
+		anchorsMaintainCase,
+		tocMinHeadingLevel,
+		tocMaxHeadingLevel,
+	};
+	return {
+		...base,
+		remarkPlugins: [
+			...beforeDefaultRemarkPlugins,
+			...defaultRemarkPlugins,
+			[remarkDocusaurusPageData, pageDataOptions],
+			...remarkPlugins,
+		],
+		rehypePlugins: [...beforeDefaultRehypePlugins, ...rehypePlugins],
+		recmaPlugins: [...recmaPlugins, recmaDocusaurusPageExports],
+	};
+}
+
+function escapeMarkdownHeadingIds(source) {
+	const lines = source.split('\n');
+	let fence;
+
+	for (let index = 0; index < lines.length; index++) {
+		const line = lines[index];
+		const match = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+		if (match) {
+			const marker = match[1];
+			if (fence === undefined) {
+				fence = { character: marker[0], length: marker.length };
+			} else if (
+				marker[0] === fence.character &&
+				marker.length >= fence.length &&
+				/^[\t ]*\r?$/.test(line.slice(match[0].length))
+			) {
+				fence = undefined;
+			}
+			continue;
+		}
+		if (fence !== undefined) continue;
+		lines[index] = line.replace(/^#{1,6}(?!#).*/, (heading) =>
+			heading.replace('{#', '\\{#').replace('\\\\{#', '\\{#'),
+		);
+	}
+
+	return lines.join('\n');
+}
+
+export function compileDocusaurusMdx(source, id, options = {}) {
+	return compileMdx(escapeMarkdownHeadingIds(source), id, compileOptions(options));
+}
+
+export function compileDocusaurusMdxSync(source, id, options = {}) {
+	return compileMdxSync(escapeMarkdownHeadingIds(source), id, compileOptions(options));
+}

package/src/version.js

@@ -0,0 +1,68 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+export const SUPPORTED_DOCUSARUS_VERSION = '3.10.1';
+export const MINIMUM_DOCUSARUS_NODE_VERSION = '20.0.0';
+
+const packageRequire = createRequire(import.meta.url);
+
+function versionParts(version) {
+	return version.split('.', 3).map((part) => Number.parseInt(part, 10) || 0);
+}
+
+function versionAtLeast(version, minimum) {
+	const received = versionParts(version);
+	const required = versionParts(minimum);
+	for (let index = 0; index < 3; index++) {
+		if (received[index] > required[index]) return true;
+		if (received[index] < required[index]) return false;
+	}
+	return true;
+}
+
+function siteRequire(siteDir) {
+	return createRequire(path.join(path.resolve(siteDir), 'package.json'));
+}
+
+export async function resolveDocusaurusCore(siteDir) {
+	let manifestPath;
+	try {
+		manifestPath = siteRequire(siteDir).resolve('@docusaurus/core/package.json');
+	} catch (siteError) {
+		try {
+			manifestPath = packageRequire.resolve('@docusaurus/core/package.json');
+		} catch {
+			throw new Error(
+				`[@octanejs/docusaurus] Could not resolve @docusaurus/core from ${path.resolve(siteDir)}. ` +
+					`Install @docusaurus/core@${SUPPORTED_DOCUSARUS_VERSION} in the site.`,
+				{ cause: siteError },
+			);
+		}
+	}
+	const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+	return {
+		manifestPath,
+		packageRoot: path.dirname(manifestPath),
+		version: String(manifest.version ?? ''),
+	};
+}
+
+export function assertSupportedDocusaurusRuntime(resolved, options = {}) {
+	if (!versionAtLeast(process.versions.node, MINIMUM_DOCUSARUS_NODE_VERSION)) {
+		throw new Error(
+			`[@octanejs/docusaurus] Docusaurus ${SUPPORTED_DOCUSARUS_VERSION} requires Node ` +
+				`${MINIMUM_DOCUSARUS_NODE_VERSION} or newer; received ${process.versions.node}.`,
+		);
+	}
+	if (
+		resolved.version !== SUPPORTED_DOCUSARUS_VERSION &&
+		options.allowUnsupportedVersion !== true
+	) {
+		throw new Error(
+			`[@octanejs/docusaurus] This integration is pinned to @docusaurus/core@` +
+				`${SUPPORTED_DOCUSARUS_VERSION}; resolved ${resolved.version || 'an unknown version'}. ` +
+				`Pass allowUnsupportedVersion: true only for an explicit compatibility experiment.`,
+		);
+	}
+}

package/src/vite.js

@@ -0,0 +1,202 @@
+import path from 'node:path';
+import { createOctaneCompiler } from 'octane/compiler/bundler';
+import { compileDocusaurusMdx } from './mdx.js';
+import { loadDocusaurusSite } from './load-site.js';
+import { createDocusaurusManifest, resolveDocusaurusId } from './manifest.js';
+
+export const DOCUSAURUS_MANIFEST_ID = 'virtual:octane-docusaurus-manifest';
+const RESOLVED_DOCUSAURUS_MANIFEST_ID = `\0${DOCUSAURUS_MANIFEST_ID}`;
+
+function cleanId(id) {
+	return id.split(/[?#]/, 1)[0];
+}
+
+function createContentIndex(manifest) {
+	const result = new Map();
+	for (const [source, metadata] of Object.entries(manifest.content)) {
+		const resolved = path.isAbsolute(source) ? source : resolveDocusaurusId(source, manifest);
+		if (resolved !== null) result.set(cleanId(resolved), metadata);
+	}
+	return result;
+}
+
+function serializableManifest(manifest) {
+	return JSON.stringify(manifest)
+		.replace(/\u2028/g, '\\u2028')
+		.replace(/\u2029/g, '\\u2029')
+		.replace(/</g, '\\u003c');
+}
+
+function createSharedState(options) {
+	let loaded;
+	let manifest;
+	let contentIndex = new Map();
+	let loading;
+	let root = path.resolve(process.cwd(), options.siteDir ?? '.');
+
+	async function refresh() {
+		if (loading) return loading;
+		loading = (async () => {
+			const nextLoaded = await loadDocusaurusSite({
+				siteDir: root,
+				outDir: options.outDir,
+				config: options.config,
+				locale: options.locale,
+				automaticBaseUrlLocalizationDisabled: options.automaticBaseUrlLocalizationDisabled,
+				allowUnsupportedVersion: options.allowUnsupportedVersion,
+			});
+			const nextManifest = await createDocusaurusManifest(nextLoaded);
+			const nextContentIndex = createContentIndex(nextManifest);
+			loaded = nextLoaded;
+			manifest = nextManifest;
+			contentIndex = nextContentIndex;
+			return nextManifest;
+		})().finally(() => {
+			loading = undefined;
+		});
+		return loading;
+	}
+
+	return {
+		setRoot(value) {
+			root = path.resolve(value, options.siteDir ?? '.');
+		},
+		refresh,
+		async getManifest() {
+			return loading ?? manifest ?? refresh();
+		},
+		getLoaded() {
+			return loaded;
+		},
+		async metadataFor(id) {
+			await this.getManifest();
+			return contentIndex.get(cleanId(id));
+		},
+	};
+}
+
+export function docusaurusBridge(options = {}, shared = createSharedState(options)) {
+	return {
+		name: 'octane-docusaurus-bridge',
+		enforce: 'pre',
+		api: {
+			getManifest: () => shared.getManifest(),
+			reload: () => shared.refresh(),
+		},
+		async configResolved(config) {
+			shared.setRoot(config.root ?? process.cwd());
+			await shared.refresh();
+		},
+		async buildStart() {
+			const manifest = await shared.getManifest();
+			const loaded = shared.getLoaded();
+			const siteConfigPath = loaded?.site?.props?.siteConfigPath;
+			if (typeof siteConfigPath === 'string') this.addWatchFile?.(siteConfigPath);
+			for (const plugin of loaded?.site?.props?.plugins ?? []) {
+				if (typeof plugin.getPathsToWatch !== 'function') continue;
+				for (const watched of (await plugin.getPathsToWatch()) ?? []) {
+					this.addWatchFile?.(watched);
+				}
+			}
+			for (const source of Object.keys(manifest.content)) {
+				const resolved = path.isAbsolute(source) ? source : resolveDocusaurusId(source, manifest);
+				if (resolved !== null) this.addWatchFile?.(cleanId(resolved));
+			}
+		},
+		async watchChange() {
+			await shared.refresh();
+		},
+		async resolveId(id) {
+			if (id === DOCUSAURUS_MANIFEST_ID) return RESOLVED_DOCUSAURUS_MANIFEST_ID;
+			const manifest = await shared.getManifest();
+			return resolveDocusaurusId(id, manifest);
+		},
+		async load(id) {
+			if (id !== RESOLVED_DOCUSAURUS_MANIFEST_ID) return null;
+			return `export default ${serializableManifest(await shared.getManifest())};\n`;
+		},
+	};
+}
+
+export function docusaurusMdx(options = {}) {
+	const { ssr: forceSsr, md, hmr, profile, metadata: metadataOption, ...compileOptions } = options;
+	let hmrEnabled = hmr;
+	let projectRoot = process.cwd();
+	let profileIds = createOctaneCompiler({ root: projectRoot });
+	const includeMd = md !== false;
+	const warnedByFile = new Map();
+
+	return {
+		name: 'octane-docusaurus-mdx',
+		enforce: 'pre',
+		configResolved(config) {
+			projectRoot = config.root ?? projectRoot;
+			profileIds = createOctaneCompiler({ root: projectRoot });
+			if (hmrEnabled === undefined) hmrEnabled = config.command === 'serve';
+		},
+		watchChange(id) {
+			profileIds.invalidate(id);
+			warnedByFile.delete(cleanId(id));
+		},
+		async transform(code, id, transformOptions) {
+			const [file, query = ''] = id.split('?');
+			if (!(file.endsWith('.mdx') || (includeMd && file.endsWith('.md')))) return null;
+			if (/(^|&)(raw|url|inline|worker|sharedworker)(=|&|$)/.test(query)) return null;
+			const ssr =
+				forceSsr !== undefined
+					? forceSsr
+					: transformOptions?.ssr === true || this.environment?.config?.consumer === 'server';
+			const profiling = !ssr && profile === true;
+			const profileIdentity = profiling ? profileIds.resolveProfileModuleId(file) : null;
+			for (const dependency of profileIdentity?.dependencies ?? []) {
+				this.addWatchFile?.(dependency);
+			}
+			const metadata =
+				typeof metadataOption === 'function' ? await metadataOption(file) : metadataOption;
+			const result = await compileDocusaurusMdx(code, profileIdentity?.id ?? file, {
+				...compileOptions,
+				metadata,
+				mode: ssr ? 'server' : 'client',
+				hmr: !ssr && !!hmrEnabled,
+				dev: !ssr && !!hmrEnabled,
+				profile: profiling,
+			});
+			let warned = warnedByFile.get(file);
+			if (warned === undefined) {
+				warned = new Set();
+				warnedByFile.set(file, warned);
+			}
+			for (const diagnostic of result.diagnostics) {
+				const key = `${diagnostic.code}:${diagnostic.start.offset}:${diagnostic.end.offset}:${diagnostic.message}`;
+				if (warned.has(key)) continue;
+				warned.add(key);
+				this.warn?.({
+					code: diagnostic.code,
+					message: diagnostic.message,
+					id: diagnostic.filename,
+					loc: {
+						file: diagnostic.filename,
+						line: diagnostic.start.line,
+						column: diagnostic.start.column,
+					},
+				});
+			}
+			return result;
+		},
+	};
+}
+
+export function docusaurus(options = {}) {
+	const shared = createSharedState(options);
+	const bridge = docusaurusBridge(options, shared);
+	const mdx = docusaurusMdx({
+		...options.mdx,
+		metadata: async (id) => {
+			const fromSite = await shared.metadataFor(id);
+			if (fromSite !== undefined) return fromSite;
+			const configured = options.mdx?.metadata;
+			return typeof configured === 'function' ? configured(id) : configured;
+		},
+	});
+	return [bridge, mdx];
+}

package/types/index.d.ts

@@ -0,0 +1,107 @@
+export declare const SUPPORTED_DOCUSARUS_VERSION = '3.10.1';
+export declare const MINIMUM_DOCUSARUS_NODE_VERSION = '20.0.0';
+
+export interface ResolvedDocusaurusCore {
+	manifestPath: string;
+	packageRoot: string;
+	version: string;
+}
+
+export interface LoadDocusaurusSiteOptions {
+	siteDir?: string;
+	outDir?: string;
+	config?: string;
+	locale?: string;
+	automaticBaseUrlLocalizationDisabled?: boolean;
+	allowUnsupportedVersion?: boolean;
+}
+
+export interface LoadedDocusaurusSite {
+	corePath: string;
+	docusaurusVersion: string;
+	site: {
+		props: Record<string, any> & {
+			siteDir: string;
+			generatedFilesDir: string;
+			outDir: string;
+			baseUrl: string;
+			routesPaths: string[];
+			routes: any[];
+			plugins: any[];
+		};
+		params: Record<string, any>;
+	};
+}
+
+export interface ImportedDocusaurusModule {
+	__import: true;
+	path: string;
+	query?: unknown;
+}
+
+export type DocusaurusModule = string | ImportedDocusaurusModule;
+
+export interface DocusaurusManifestRoute {
+	id: string;
+	path: string;
+	component: DocusaurusModule;
+	exact: boolean;
+	priority?: number;
+	modules?: Record<string, DocusaurusModule | DocusaurusModule[]>;
+	context?: unknown;
+	props?: unknown;
+	metadata?: unknown;
+	plugin?: unknown;
+	attributes?: Record<string, unknown>;
+	children: DocusaurusManifestRoute[];
+}
+
+export interface DocusaurusManifestAliases {
+	site: string;
+	generated: string;
+	docs: string;
+	theme: Record<string, string>;
+	themeOriginal: Record<string, string>;
+	themeInit: Record<string, string>;
+}
+
+export interface DocusaurusManifest {
+	schemaVersion: 1;
+	docusaurusVersion: string;
+	siteDir: string;
+	generatedFilesDir: string;
+	outDir: string;
+	baseUrl: string;
+	routesPaths: string[];
+	routes: DocusaurusManifestRoute[];
+	globalData: Record<string, unknown>;
+	content: Record<string, Record<string, any>>;
+	aliases: DocusaurusManifestAliases;
+}
+
+export declare function resolveDocusaurusCore(siteDir: string): Promise<ResolvedDocusaurusCore>;
+
+export declare function assertSupportedDocusaurusRuntime(
+	resolved: ResolvedDocusaurusCore,
+	options?: { allowUnsupportedVersion?: boolean },
+): void;
+
+export declare function loadDocusaurusSite(
+	options?: LoadDocusaurusSiteOptions,
+): Promise<LoadedDocusaurusSite>;
+
+export declare function createDocusaurusManifest(
+	loaded: LoadedDocusaurusSite,
+): Promise<DocusaurusManifest>;
+
+export declare function resolveDocusaurusId(
+	id: string,
+	manifest: DocusaurusManifest,
+): string | null;
+
+export declare function writeDocusaurusManifest(
+	manifest: DocusaurusManifest,
+	filename: string,
+): Promise<string>;
+
+export declare function readDocusaurusManifest(filename: string): Promise<DocusaurusManifest>;