@apify/docusaurus-plugin-typedoc-api 3.0.1 → 4.2.0

package/src/index.ts

@@ -2,7 +2,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import type { JSONOutput } from 'typedoc';
+import type { Options as MDXLoaderOptions } from '@docusaurus/mdx-loader';
 import type { PropVersionDocs, PropVersionMetadata } from '@docusaurus/plugin-content-docs';
 import { CURRENT_VERSION_NAME } from '@docusaurus/plugin-content-docs/server';
 import type { LoadContext, Plugin, RouteConfig } from '@docusaurus/types';
@@ -22,6 +22,7 @@ import type {
 	PackageEntryConfig,
 	PackageReflectionGroup,
 	ResolvedPackageConfig,
+	TSDDeclarationReflection,
 	VersionMetadata,
 } from './types';
 
@@ -51,6 +52,8 @@ const DEFAULT_OPTIONS: Required<DocusaurusPluginTypeDocApiOptions> = {
 	routeBasePath: 'api',
 	tsconfigName: 'tsconfig.json',
 	typedocOptions: {},
+	remarkPlugins: [],
+	rehypePlugins: [],
 	versions: {},
 };
 
@@ -96,7 +99,7 @@ export default function typedocApiPlugin(
 		if (!pkgConfig.entry || typeof pkgConfig.entry === 'string') {
 			entries.index = {
 				label: 'Index',
-				path: pkgConfig.entry ?? 'src/index.ts',
+				path: pkgConfig.entry ? String(pkgConfig.entry) : 'src/index.ts',
 			};
 		} else {
 			Object.entries(pkgConfig.entry).forEach(([importPath, entryConfig]) => {
@@ -105,7 +108,7 @@ export default function typedocApiPlugin(
 						? {
 								label: 'Index',
 								path: entryConfig,
-						  }
+							}
 						: entryConfig;
 			});
 		}
@@ -116,6 +119,7 @@ export default function typedocApiPlugin(
 
 		return {
 			entryPoints: entries,
+			packageRoot: path.normalize(path.join(projectRoot, pkgConfig.path || '.')),
 			packagePath: pkgConfig.path || '.',
 			packageSlug: pkgConfig.slug ?? path.basename(pkgConfig.path),
 			// Load later on
@@ -220,15 +224,34 @@ export default function typedocApiPlugin(
 
 						packages.sort((a, d) => options.sortPackages(a, d));
 
+						// Generate sidebars (this runs before the main sidebar is loaded)
+						const sidebars = extractSidebar(
+							packages,
+							removeScopes,
+							changelogs,
+							options.sortSidebar,
+						);
+
+						await fs.promises.writeFile(
+							path.join(
+								context.generatedFilesDir,
+								`api-sidebar-${pluginId}-${metadata.versionName}.js`,
+							),
+							`module.exports = ${JSON.stringify(sidebars, null, 2)};`,
+						);
+
+						await fs.promises.writeFile(
+							path.join(
+								context.generatedFilesDir,
+								`api-sidebar-${pluginId}-${metadata.versionName}.d.ts`,
+							),
+							`import type { SidebarConfig } from '@docusaurus/plugin-content-docs';\nexport = Array<SidebarConfig>;`,
+						);
+
 						return {
 							...metadata,
 							packages,
-							sidebars: await extractSidebar(
-								packages,
-								removeScopes,
-								changelogs,
-								options.sortSidebar,
-							),
+							sidebars,
 						};
 					}),
 				),
@@ -240,7 +263,6 @@ export default function typedocApiPlugin(
 				return;
 			}
 
-			const { createData, addRoute } = actions;
 			const docs: PropVersionDocs = {};
 
 			// Create an index of versions for quick lookups.
@@ -255,14 +277,14 @@ export default function typedocApiPlugin(
 				}
 			});
 
-			await Promise.all(
+			const rootRoutes = await Promise.all(
 				content.loadedVersions.map(async (loadedVersion) => {
 					const version = loadedVersion.versionName;
 
 					// Define version metadata for all pages. We need to use the same structure as
 					// "docs" so that we can utilize the same React components.
 					// https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-plugin-content-docs/src/index.ts#L337
-					const versionMetadata = await createData(
+					const versionMetadata = await actions.createData(
 						`version-${version}.json`,
 						JSON.stringify({
 							badge: loadedVersion.versionBadge,
@@ -275,26 +297,28 @@ export default function typedocApiPlugin(
 							noIndex: false,
 							pluginId,
 							version: loadedVersion.versionName,
-						} as PropVersionMetadata),
+						} satisfies PropVersionMetadata),
 					);
 
-					const packagesData = await createData(
+					const packagesData = await actions.createData(
 						`packages-${version}.json`,
 						JSON.stringify(formatPackagesWithoutHostInfo(loadedVersion.packages)),
 					);
 
-					const optionsContextData: ApiOptions = {
-						banner,
-						breadcrumbs,
-						gitRefName,
-						minimal,
-						pluginId,
-						scopes: removeScopes,
-					};
-					const optionsData = await createData('options.json', JSON.stringify(optionsContextData));
+					const optionsData = await actions.createData(
+						'options.json',
+						JSON.stringify({
+							banner,
+							breadcrumbs,
+							gitRefName,
+							minimal,
+							pluginId,
+							scopes: removeScopes,
+						} satisfies ApiOptions),
+					);
 
 					function createRoute(
-						info: JSONOutput.Reflection,
+						info: TSDDeclarationReflection,
 						modules?: Record<string, string>,
 					): RouteConfig {
 						return {
@@ -319,7 +343,7 @@ export default function typedocApiPlugin(
 							// Map a route for every declaration in the package (the exported APIs)
 							const subRoutes = children.map((child) => createRoute(child));
 
-							// Map a top-level package route, otherwise `DocPage` shows a page not found
+							// Map a top-level package route, otherwise `DocRoot` shows a page not found
 							subRoutes.push(
 								createRoute(
 									entry.reflection,
@@ -359,20 +383,40 @@ export default function typedocApiPlugin(
 						});
 					}
 
-					addRoute({
+					// Wrap in the `DocVersionRoot` component:
+					// https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/routes.ts#L192
+					return {
 						path: indexPermalink,
 						exact: false,
-						component: path.join(__dirname, './components/ApiPage.js'),
-						routes,
+						component: '@theme/DocVersionRoot',
+						routes: [
+							{
+								path: indexPermalink,
+								exact: false,
+								component: path.join(__dirname, './components/ApiPage.js'),
+								routes,
+								modules: {
+									options: optionsData,
+									packages: packagesData,
+								},
+							},
+						],
 						modules: {
-							options: optionsData,
-							packages: packagesData,
-							versionMetadata,
+							version: versionMetadata,
 						},
 						priority: loadedVersion.routePriority,
-					});
+					};
 				}),
 			);
+
+			// Wrap in the `DocsRoot` component:
+			// https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/routes.ts#L232
+			actions.addRoute({
+				path: normalizeUrl([context.baseUrl, options.routeBasePath ?? 'api']),
+				exact: false,
+				component: '@theme/DocsRoot',
+				routes: rootRoutes,
+			});
 		},
 
 		configureWebpack(config, isServer, utils) {
@@ -383,10 +427,16 @@ export default function typedocApiPlugin(
 			// Whitelist the folders that this webpack rule applies to, otherwise we collide with the native
 			// docs/blog plugins. We need to include the specific files only, as in polyrepo mode, the `cfg.packagePath`
 			// can be project root (where the regular docs are too).
-			const include = packageConfigs.flatMap((cfg) => [
-				path.join(options.projectRoot, cfg.packagePath, options.readmeName),
-				path.join(options.projectRoot, cfg.packagePath, options.changelogName),
-			]);
+			const include = packageConfigs.flatMap((cfg) => {
+				const list: string[] = [];
+				if (readmes) {
+					list.push(path.join(options.projectRoot, cfg.packagePath, options.readmeName));
+				}
+				if (changelogs) {
+					list.push(path.join(options.projectRoot, cfg.packagePath, options.changelogName));
+				}
+				return list;
+			});
 
 			return {
 				module: {
@@ -400,12 +450,15 @@ export default function typedocApiPlugin(
 									loader: require.resolve('@docusaurus/mdx-loader'),
 									options: {
 										admonitions: true,
-										staticDir: path.join(context.siteDir, 'static'),
-										// Since this isnt a doc/blog page, we can get
+										remarkPlugins: options.remarkPlugins,
+										rehypePlugins: options.rehypePlugins,
+										siteDir: context.siteDir,
+										staticDirs: [...context.siteConfig.staticDirectories, path.join(context.siteDir, 'static')],
+										// Since this isn't a doc/blog page, we can get
 										// away with it being a partial!
 										isMDXPartial: () => true,
 										markdownConfig: context.siteConfig.markdown,
-									},
+									} satisfies MDXLoaderOptions,
 								},
 								{
 									loader: path.resolve(__dirname, './markdownLoader.js'),

package/src/plugin/data.ts

@@ -5,10 +5,12 @@ import { JSONOutput, ReflectionKind } from 'typedoc';
 import ts from 'typescript';
 import { normalizeUrl } from '@docusaurus/utils';
 import type {
-	DeclarationReflectionMap,
 	DocusaurusPluginTypeDocApiOptions,
+	PackageEntryConfig,
 	PackageReflectionGroup,
 	ResolvedPackageConfig,
+	TSDDeclarationReflection,
+	TSDDeclarationReflectionMap,
 } from '../types';
 import { migrateToVersion0230 } from './structure/0.23';
 import { getKindSlug, getPackageSlug, joinUrl } from './url';
@@ -52,43 +54,45 @@ export async function generateJson(
 		return true;
 	}
 
-	const app = new TypeDoc.Application();
-	const tsconfig = path.join(projectRoot, options.tsconfigName!);
-
-	app.options.addReader(new TypeDoc.TSConfigReader());
-	app.options.addReader(new TypeDoc.TypeDocReader());
-
-	app.bootstrap({
-		skipErrorChecking: true,
-		// Only emit when using project references
-		emit: shouldEmit(projectRoot, tsconfig),
-		// Only document the public API by default
-		excludeExternals: true,
-		excludeInternal: true,
-		excludePrivate: true,
-		excludeProtected: true,
-		// Enable verbose logging when debugging
-		logLevel: options.debug ? 'Verbose' : 'Info',
-		inlineTags: [
-			'@link',
-			'@inheritDoc',
-			'@label',
-			'@linkcode',
-			'@linkplain',
-			'@apilink',
-			'@doclink',
-		] as `@${string}`[],
-		...options.typedocOptions,
-		// Control how config and packages are detected
-		tsconfig,
-		entryPoints: entryPoints.map((ep) => path.join(projectRoot, ep)),
-		entryPointStrategy: 'expand',
-		exclude: options.exclude,
-		// We use a fake category title so that we can fallback to the parent group
-		defaultCategory: 'CATEGORY',
-	});
+	const tsconfig = path.join(projectRoot, options.tsconfigName ?? 'tsconfig.json');
+
+	const app = await TypeDoc.Application.bootstrapWithPlugins(
+		{
+			gitRevision: options.gitRefName,
+			includeVersion: true,
+			skipErrorChecking: true,
+			// stripYamlFrontmatter: true,
+			// Only emit when using project references
+			emit: shouldEmit(projectRoot, tsconfig),
+			// Only document the public API by default
+			excludeExternals: true,
+			excludeInternal: true,
+			excludePrivate: true,
+			excludeProtected: true,
+			// Enable verbose logging when debugging
+			logLevel: options.debug ? 'Verbose' : 'Info',
+			inlineTags: [
+				'@link',
+				'@inheritDoc',
+				'@label',
+				'@linkcode',
+				'@linkplain',
+				'@apilink',
+				'@doclink',
+			] as `@${string}`[],
+			...options.typedocOptions,
+			// Control how config and packages are detected
+			tsconfig,
+			entryPoints: entryPoints.map((ep) => path.join(projectRoot, ep)),
+			entryPointStrategy: 'expand',
+			exclude: options.exclude,
+			// We use a fake category title so that we can fallback to the parent group
+			defaultCategory: '__CATEGORY__',
+		},
+		[new TypeDoc.TSConfigReader(), new TypeDoc.TypeDocReader()],
+	);
 
-	const project = app.convert();
+	const project = await app.convert();
 
 	if (project) {
 		await app.generateJson(project, outFile);
@@ -102,9 +106,9 @@ export async function generateJson(
 }
 
 export function createReflectionMap(
-	items: JSONOutput.DeclarationReflection[] = [],
-): DeclarationReflectionMap {
-	const map: DeclarationReflectionMap = {};
+	items: TSDDeclarationReflection[] = [],
+): TSDDeclarationReflectionMap {
+	const map: TSDDeclarationReflectionMap = {};
 
 	items.forEach((item) => {
 		map[item.id] = item;
@@ -139,10 +143,10 @@ export function loadPackageJsonAndDocs(
 }
 
 export function addMetadataToReflections(
-	project: JSONOutput.ProjectReflection,
+	project: JSONOutput.DeclarationReflection,
 	packageSlug: string,
 	urlPrefix: string,
-): JSONOutput.ProjectReflection {
+): TSDDeclarationReflection {
 	const permalink = `/${joinUrl(urlPrefix, packageSlug)}`;
 
 	if (project.children) {
@@ -170,13 +174,14 @@ export function addMetadataToReflections(
 		});
 	}
 
+	// @ts-expect-error Not sure why this fails
 	return {
 		...project,
 		permalink: normalizeUrl([permalink]),
 	};
 }
 
-function mergeReflections(base: JSONOutput.ProjectReflection, next: JSONOutput.ProjectReflection) {
+function mergeReflections(base: TSDDeclarationReflection, next: TSDDeclarationReflection) {
 	if (Array.isArray(base.children) && Array.isArray(next.children)) {
 		base.children.push(...next.children);
 	}
@@ -198,7 +203,7 @@ function mergeReflections(base: JSONOutput.ProjectReflection, next: JSONOutput.P
 	}
 }
 
-function sortReflectionGroups(reflections: JSONOutput.ProjectReflection[]) {
+function sortReflectionGroups(reflections: TSDDeclarationReflection[]) {
 	reflections.forEach((reflection) => {
 		const map = createReflectionMap(reflection.children);
 		const sort = (a: number, b: number) => (map[a].name < map[b].name ? -1 : 1);
@@ -217,7 +222,7 @@ function sortReflectionGroups(reflections: JSONOutput.ProjectReflection[]) {
 	});
 }
 
-function matchesEntryPoint(
+function sourceFileMatchesEntryPoint(
 	sourceFile: string,
 	entryPoint: string,
 	{ deep, single }: { deep: boolean; single: boolean },
@@ -244,11 +249,51 @@ function matchesEntryPoint(
 	);
 }
 
+function modContainsEntryPoint(
+	mod: JSONOutput.DeclarationReflection,
+	entry: PackageEntryConfig,
+	meta: {
+		allSourceFiles: Record<string, boolean>;
+		packagePath: string;
+		packageRoot: string;
+		isSinglePackage: boolean;
+		isUsingDeepImports: boolean;
+	},
+) {
+	const relModSources = mod.sources ?? [];
+	const relModSourceFile = relModSources.find((sf) => !!sf.fileName)?.fileName ?? '';
+	const relEntryPoint = joinUrl(meta.packagePath, entry.path);
+
+	// Monorepos of 1 package don't have sources, so use the child sources.
+	// They also don't use full paths like "package/src/index.ts" and simply use "index.ts",
+	// so account for those entry points also.
+	if (!relModSourceFile) {
+		const absEntryPoint = path.normalize(path.join(meta.packageRoot, entry.path));
+		const relEntryPointName = path.basename(relEntryPoint);
+		const entryPointInSourceFiles =
+			!!meta.allSourceFiles[absEntryPoint] ||
+			!!meta.allSourceFiles[relEntryPoint] ||
+			(relEntryPointName.startsWith('index.') && !!meta.allSourceFiles[relEntryPointName]);
+
+		if (entryPointInSourceFiles) {
+			return sourceFileMatchesEntryPoint(relEntryPoint, relEntryPoint, {
+				deep: meta.isUsingDeepImports,
+				single: meta.isSinglePackage,
+			});
+		}
+	}
+
+	return sourceFileMatchesEntryPoint(relModSourceFile, relEntryPoint, {
+		deep: meta.isUsingDeepImports,
+		single: meta.isSinglePackage,
+	});
+}
+
 function extractReflectionModules(
 	project: JSONOutput.ProjectReflection,
 	isSinglePackage: boolean,
-): JSONOutput.ProjectReflection[] {
-	const modules: JSONOutput.ProjectReflection[] = [];
+): JSONOutput.DeclarationReflection[] {
+	const modules: JSONOutput.DeclarationReflection[] = [];
 
 	const inheritChildren = () => {
 		project.children?.forEach((child) => {
@@ -267,7 +312,7 @@ function extractReflectionModules(
 			// No "module" children:
 			//	- Polyrepos
 			//	- Monorepos with 1 package
-			modules.push(project);
+			modules.push(project as unknown as JSONOutput.DeclarationReflection);
 		} else {
 			// Has "module" children:
 			//	- Polyrepos with deep imports
@@ -285,6 +330,28 @@ function extractReflectionModules(
 	return modules;
 }
 
+function buildSourceFileNameMap(
+	project: JSONOutput.ProjectReflection,
+	modChildren: JSONOutput.DeclarationReflection[],
+) {
+	const map: Record<string, boolean> = {};
+	const cwd = process.cwd();
+
+	Object.values(project.symbolIdMap).forEach((symbol) => {
+		// absolute
+		map[path.normalize(path.join(cwd, symbol.sourceFileName))] = true;
+	});
+
+	modChildren.forEach((child) => {
+		child.sources?.forEach((sf) => {
+			// relative
+			map[sf.fileName] = true;
+		});
+	});
+
+	return map;
+}
+
 export function flattenAndGroupPackages(
 	packageConfigs: ResolvedPackageConfig[],
 	project: JSONOutput.ProjectReflection,
@@ -297,20 +364,22 @@ export function flattenAndGroupPackages(
 
 	// Loop through every TypeDoc module and group based on package and entry point
 	const packages: Record<string, PackageReflectionGroup> = {};
-	const packagesWithDeepImports: JSONOutput.ProjectReflection[] = [];
+	const packagesWithDeepImports: TSDDeclarationReflection[] = [];
 
 	modules.forEach((mod) => {
-		const relSourceFile = mod.sources?.[0]?.fileName ?? '';
+		const allSourceFiles = buildSourceFileNameMap(project, mod.children ?? []);
 
 		packageConfigs.some((cfg) =>
 			Object.entries(cfg.entryPoints).some(([importPath, entry]) => {
-				const relEntryPoint = joinUrl(cfg.packagePath, entry.path);
 				const isUsingDeepImports = !entry.path.match(/\.tsx?$/);
 
 				if (
-					!matchesEntryPoint(relSourceFile, relEntryPoint, {
-						deep: isUsingDeepImports,
-						single: isSinglePackage,
+					!modContainsEntryPoint(mod, entry, {
+						allSourceFiles,
+						isSinglePackage,
+						isUsingDeepImports,
+						packagePath: cfg.packagePath,
+						packageRoot: cfg.packageRoot,
 					})
 				) {
 					return false;

package/src/plugin/sidebar.ts

@@ -1,16 +1,17 @@
 import { JSONOutput } from 'typedoc';
 import { normalizeUrl } from '@docusaurus/utils';
 import type {
-	DeclarationReflectionMap,
 	DocusaurusPluginTypeDocApiOptions,
 	PackageReflectionGroup,
 	SidebarItem,
+	TSDDeclarationReflection,
+	TSDDeclarationReflectionMap,
 } from '../types';
 import { removeScopes } from '../utils/links';
 import { createReflectionMap } from './data';
 
 export function groupSidebarItems(
-	map: DeclarationReflectionMap,
+	map: TSDDeclarationReflectionMap,
 	groups: JSONOutput.ReflectionGroup[],
 ): SidebarItem[] {
 	const items: SidebarItem[] = [];
@@ -65,7 +66,7 @@ export function groupSidebarItems(
 	return items;
 }
 
-export function extractReflectionSidebar(pkg: JSONOutput.ProjectReflection): SidebarItem[] {
+export function extractReflectionSidebar(pkg: TSDDeclarationReflection): SidebarItem[] {
 	return pkg.groups ? groupSidebarItems(createReflectionMap(pkg.children), pkg.groups) : [];
 }
 

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { JSONOutput, TypeDocOptions } from 'typedoc';
+import type { MDXPlugin } from '@docusaurus/mdx-loader';
 import type {
 	PropSidebarItem,
 	VersionBanner,
@@ -28,26 +29,10 @@ export interface DocusaurusPluginTypeDocApiOptions
 	sortPackages?: (a: PackageReflectionGroup, d: PackageReflectionGroup) => number;
 	sortSidebar?: (a: string, d: string) => number;
 	tsconfigName?: string;
-	typedocOptions?: Partial<
-		Pick<
-			TypeDocOptions,
-			| 'commentStyle'
-			| 'disableSources'
-			| 'emit'
-			| 'excludeExternals'
-			| 'excludeInternal'
-			| 'excludeNotDocumented'
-			| 'excludePrivate'
-			| 'excludeProtected'
-			| 'excludeTags'
-			| 'externalPattern'
-			| 'logger'
-			| 'logLevel'
-			| 'sort'
-			| 'treatWarningsAsErrors'
-			| 'validation'
-		>
-	>;
+	typedocOptions?: Partial<TypeDocOptions>;
+
+	remarkPlugins: MDXPlugin[];
+	rehypePlugins: MDXPlugin[];
 
 	// Versioning, based on Docusaurus
 	disableVersioning?: boolean;
@@ -70,6 +55,7 @@ export interface PackageConfig {
 
 export interface ResolvedPackageConfig {
 	entryPoints: Record<string, PackageEntryConfig>;
+	packageRoot: string;
 	packagePath: string;
 	packageSlug: string;
 	packageName: string;
@@ -123,7 +109,7 @@ export interface TOCItem {
 export interface PackageReflectionGroupEntry {
 	index: boolean;
 	label: string;
-	reflection: JSONOutput.ProjectReflection;
+	reflection: TSDDeclarationReflection;
 	urlSlug: string;
 }
 
@@ -143,20 +129,25 @@ export interface ApiMetadata {
 	nextId?: number;
 }
 
-export type DeclarationReflectionMap = Record<number, JSONOutput.DeclarationReflection>;
+// TYPEDOC COMPAT
+
+export interface TSDReflection extends Omit<JSONOutput.Reflection, 'signatures'>, ApiMetadata {
+	signatures: TSDSignatureReflection[];
+	// Added by us for convenience
+	parentId?: number;
+}
+
+export interface TSDDeclarationReflection
+	extends Omit<JSONOutput.DeclarationReflection, 'children' | 'signatures'>,
+		ApiMetadata {
+	children?: TSDDeclarationReflection[];
+	signatures: TSDSignatureReflection[];
+}
 
-declare module 'typedoc/dist/lib/serialization/schema' {
-	interface Reflection extends ApiMetadata {
-		// Not typed but used in the templates
-		declaration?: DeclarationReflection;
-		// Added by us for convenience
-		parentId?: number;
-	}
+export type TSDDeclarationReflectionMap = Record<number, TSDDeclarationReflection>;
 
-	interface Type {
-		// Not typed but used in the templates
-		declaration?: DeclarationReflection;
-	}
+export interface TSDSignatureReflection extends JSONOutput.SignatureReflection {
+	// declaration: TSDDeclarationReflection;
 }
 
 declare global {

package/src/utils/helpers.ts

@@ -0,0 +1,4 @@
+export function escapeMdx(value: string | null): string | null {
+	// New values are unicode!
+	return value?.replace('<', '＜').replace('>', '＞') ?? null;
+}