[Docs] Fix API reference

Author: adamziel

package-lock.json

@@ -79,6 +79,8 @@
 		"@codemirror/search": "6.5.11",
 		"@codemirror/state": "6.5.2",
 		"@codemirror/view": "6.38.3",
+		"@docusaurus/plugin-content-docs": "3.9.2",
+		"@docusaurus/theme-common": "3.9.2",
 		"@preact/signals-react": "1.3.6",
 		"@reduxjs/toolkit": "2.6.1",
 		"@types/xml2js": "0.4.14",

package.json

@@ -25,11 +25,7 @@ const config = {
 	projectName: 'wordpress-playground', // Usually your repo name.
 
 	onBrokenLinks: 'throw',
-	markdown: {
-		hooks: {
-			onBrokenMarkdownLinks: 'throw',
-		},
-	},
+	onBrokenMarkdownLinks: 'throw',
 
 	// Even if you don't use internalization, you can use this field to set useful
 	// metadata like HTML lang. For example, if your site is Chinese, you may want
@@ -71,6 +67,7 @@ const config = {
 	},
 	themes: ['@docusaurus/theme-live-codeblock'],
 	plugins: [
+		'./plugins/docusaurus-dedupe-aliases.js',
 		getDocusaurusPluginTypedocApiConfig(),
 		[
 			'@docusaurus/plugin-ideal-image',
@@ -266,7 +263,7 @@ function getDocusaurusPluginTypedocApiConfig() {
 	};
 
 	return [
-		'docusaurus-plugin-typedoc-api',
+		require.resolve('./plugins/typedoc-api-wrapper.js'),
 		{
 			projectRoot,
 			packages,

packages/docs/site/docusaurus.config.js

@@ -0,0 +1,90 @@
+const fs = require('fs');
+const moduleRequire = require('module').createRequire(__dirname);
+
+const PACKAGES_TO_DEDUPE = [
+	'@docusaurus/plugin-content-docs',
+	'@docusaurus/theme-common',
+	'@docusaurus/theme-search-algolia',
+];
+
+function getExportKeys(exportsField) {
+	if (!exportsField) {
+		return ['.'];
+	}
+
+	if (typeof exportsField === 'string') {
+		return ['.'];
+	}
+
+	if (Array.isArray(exportsField)) {
+		return ['.'];
+	}
+
+	if (typeof exportsField === 'object') {
+		const keys = new Set(['.']);
+		for (const key of Object.keys(exportsField)) {
+			if (key === 'default' || key.includes('*')) {
+				continue;
+			}
+			keys.add(key);
+		}
+		return Array.from(keys);
+	}
+
+	return ['.'];
+}
+
+function normalizeSubpath(pkgName, subpath) {
+	if (subpath === '.' || !subpath) {
+		return pkgName;
+	}
+	return `${pkgName}/${subpath.replace(/^\.\//, '')}`;
+}
+
+function buildAliasesForPackage(pkgName) {
+	let pkgJsonPath;
+	try {
+		pkgJsonPath = moduleRequire.resolve(`${pkgName}/package.json`);
+	} catch (error) {
+		console.warn(
+			`docusaurus-dedupe-aliases: unable to resolve ${pkgName}`,
+			error
+		);
+		return [];
+	}
+
+	const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+	const exportKeys = getExportKeys(pkgJson.exports);
+
+	return exportKeys.flatMap((subpath) => {
+		const specifier = normalizeSubpath(pkgName, subpath);
+		try {
+			const target = moduleRequire.resolve(specifier);
+			const aliasKey =
+				subpath === '.' ? `${pkgName}$` : specifier.replace(/\\/g, '/');
+			return [[aliasKey, target]];
+		} catch (error) {
+			console.warn(
+				`docusaurus-dedupe-aliases: unable to resolve specifier ${specifier}`,
+				error
+			);
+			return [];
+		}
+	});
+}
+
+module.exports = function docusaurusDedupeAliases() {
+	const aliasEntries = PACKAGES_TO_DEDUPE.flatMap(buildAliasesForPackage);
+	const aliases = Object.fromEntries(aliasEntries);
+
+	return {
+		name: 'docusaurus-dedupe-aliases',
+		configureWebpack() {
+			return {
+				resolve: {
+					alias: aliases,
+				},
+			};
+		},
+	};
+};

packages/docs/site/plugins/docusaurus-dedupe-aliases.js

@@ -0,0 +1,74 @@
+const path = require('path');
+const typedocApiPlugin = require('docusaurus-plugin-typedoc-api');
+
+const typedocPackageRoot = path.dirname(
+	require.resolve('docusaurus-plugin-typedoc-api/package.json')
+);
+
+const componentMap = new Map(
+	['ApiPage', 'ApiIndex', 'ApiItem', 'ApiChangelog'].map((name) => [
+		path.join(typedocPackageRoot, `lib/components/${name}.js`),
+		path.join(__dirname, `../src/typedoc/${name}.tsx`),
+	])
+);
+
+function remapComponent(componentPath) {
+	if (!componentPath) {
+		return componentPath;
+	}
+
+	const normalized = path.normalize(componentPath);
+	for (const [original, replacement] of componentMap.entries()) {
+		if (normalized === original) {
+			return replacement;
+		}
+	}
+
+	return componentPath;
+}
+
+function remapRoutes(routes) {
+	if (!routes) {
+		return routes;
+	}
+
+	return routes.map(remapRoute);
+}
+
+function remapRoute(route) {
+	if (!route) {
+		return route;
+	}
+
+	return {
+		...route,
+		component: remapComponent(route.component),
+		routes: remapRoutes(route.routes),
+	};
+}
+
+module.exports = function typedocApiWrapper(context, options) {
+	const plugin = typedocApiPlugin(context, options);
+	const originalContentLoaded = plugin.contentLoaded?.bind(plugin);
+
+	return {
+		...plugin,
+		async contentLoaded(args) {
+			if (!originalContentLoaded) {
+				return;
+			}
+
+			const patchedActions = {
+				...args.actions,
+				addRoute(routeConfig) {
+					return args.actions.addRoute(remapRoute(routeConfig));
+				},
+			};
+
+			return originalContentLoaded({
+				...args,
+				actions: patchedActions,
+			});
+		},
+	};
+};

packages/docs/site/plugins/typedoc-api-wrapper.js

@@ -0,0 +1,4 @@
+import type { ComponentType } from 'react';
+import ApiChangelog from 'docusaurus-plugin-typedoc-api/lib/components/ApiChangelog.js';
+
+export default ApiChangelog as ComponentType<any>;

packages/docs/site/src/typedoc/ApiChangelog.tsx

@@ -0,0 +1,4 @@
+import type { ComponentType } from 'react';
+import ApiIndex from 'docusaurus-plugin-typedoc-api/lib/components/ApiIndex.js';
+
+export default ApiIndex as ComponentType<any>;

packages/docs/site/src/typedoc/ApiIndex.tsx

@@ -0,0 +1,4 @@
+import type { ComponentType } from 'react';
+import ApiItem from 'docusaurus-plugin-typedoc-api/lib/components/ApiItem.js';
+
+export default ApiItem as ComponentType<any>;

packages/docs/site/src/typedoc/ApiItem.tsx

@@ -0,0 +1,4 @@
+import type { ComponentType } from 'react';
+import ApiPage from 'docusaurus-plugin-typedoc-api/lib/components/ApiPage.js';
+
+export default ApiPage as ComponentType<any>;