fix(docusaurus): bootstrap TypeDoc using API instead of spawnSync to …

…avoid cross-platform issues

.changeset/odd-pants-invite.md

@@ -0,0 +1,5 @@
+---
+'docusaurus-plugin-typedoc': patch
+---
+
+- Bootstrap TypeDoc using API instead of spawnSync to avoid cross-platform issues (#762).

packages/docusaurus-plugin-typedoc/package.json

@@ -3,8 +3,7 @@
   "version": "1.2.2",
   "description": "A Docusaurus plugin to integrate TypeDoc ( + typedoc-plugin-markdown ) into a Docusaurus project.",
   "exports": {
-    ".": "./dist/index.js",
-    "./typedoc": "./dist/plugins/typedoc.js"
+    ".": "./dist/index.js"
   },
   "type": "module",
   "files": [
@@ -24,7 +23,7 @@
   },
   "scripts": {
     "lint": "eslint ./src",
-    "prebuild": "rm -rf dist && prebuild-options",
+    "prebuild": "rm -rf dist && copyfiles --up 1 ./src/**/*.cjs ./dist/",
     "prepublishOnly": "npm run lint && npm run build",
     "build": "tsc",
     "pretest": "rm -rf ./test/out && docusaurus generate-typedoc",
@@ -39,7 +38,7 @@
     "plugin"
   ],
   "devDependencies": {
-    "@docusaurus/core": "^3.6.1",
-    "@docusaurus/types": "^3.6.1"
+    "@docusaurus/core": "^3.7.0",
+    "@docusaurus/types": "^3.7.0"
   }
 }

packages/docusaurus-plugin-typedoc/src/index.ts

@@ -2,4 +2,4 @@
  * @module core
  */
 export { PluginOptions } from './models.js';
-export { default } from './plugins/docusaurus.js';
+export { default } from './plugin/docusaurus.js';

packages/docusaurus-plugin-typedoc/src/options/declarations.ts

@@ -1,19 +1,6 @@
 import { DeclarationOption, ParameterType } from 'typedoc';
 import { DEFAULT_SIDEBAR_OPTIONS } from './options.js';
 
-/**
- * Used internally to pass options from docusaurus.config to TypeDoc.
- *
- * @internal
- *
- * @hidden
- */
-export const docusaurusConfigOptions: Partial<DeclarationOption> = {
-  help: 'docusaurus.config options - should not be used if running as a docusaurus plugin.',
-  type: ParameterType.String,
-  defaultValue: '{}',
-};
-
 /**
  * **autoConfiguration**
  *

packages/docusaurus-plugin-typedoc/src/options/options.ts

@@ -35,10 +35,7 @@ export function getPluginOptions(
       ...opts.sidebar,
     },
     plugin: [
-      ...new Set([
-        ...['typedoc-plugin-markdown', 'docusaurus-plugin-typedoc/typedoc'],
-        ...(opts.plugin || []),
-      ]),
+      ...new Set([...['typedoc-plugin-markdown'], ...(opts.plugin || [])]),
     ],
   };
 

packages/docusaurus-plugin-typedoc/src/plugins/docusaurus.ts → packages/docusaurus-plugin-typedoc/src/plugin/docusaurus.ts

@@ -1,9 +1,8 @@
-import { spawnSync } from 'child_process';
 import * as fs from 'fs';
-import * as path from 'path';
+import { MarkdownRendererEvent, NavigationItem } from 'typedoc-plugin-markdown';
 import { PluginOptions } from '../models.js';
 import { getPluginOptions } from '../options/options.js';
-import { presets } from '../options/presets.js';
+import { writeSidebar } from './sidebar.js';
 
 export default async function pluginDocusaurus(
   context: any,
@@ -35,27 +34,39 @@ export default async function pluginDocusaurus(
  * Initiates a new typedoc Application bootstrapped with plugin options
  */
 async function generateTypedoc(context: any, opts: Partial<any>) {
+  // get plugin options
+  const options = getPluginOptions(context, opts);
+
   // create outDir if it doesn't exist
-  const outputDir = path.join(context?.siteDir, presets.out);
-  if (!fs.existsSync(outputDir)) {
-    fs.mkdirSync(outputDir, { recursive: true });
+  if (!fs.existsSync(options.out)) {
+    fs.mkdirSync(options.out, { recursive: true });
   }
 
-  const { plugin, ...options } = getPluginOptions(context, opts);
-
-  // spawn typedoc process and pass docusaurus.config options as a string
+  // configure options for typedoc
+  const {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    id,
+    siteDir,
+    numberPrefixParser,
+    docsPresetPath,
+    sidebar,
+    ...optionsPassedToTypeDoc
+  } = options;
 
-  const typedocExecutable = process.platform === 'win32' ? 'typedoc.cmd' : 'typedoc';
+  const typeDocApp = await import('./typedoc.cjs');
 
-  spawnSync(
-    typedocExecutable,
-    [
-      ...plugin.flatMap((plugin) => ['--plugin', plugin]),
-      '--docusaurusConfigOptions',
-      `${JSON.stringify(options)}`,
-    ],
-    {
-      stdio: 'inherit',
+  // bootstrap typedoc with options
+  await typeDocApp.bootstrap(
+    optionsPassedToTypeDoc,
+    async (renderer: MarkdownRendererEvent) => {
+      writeSidebar(
+        renderer.navigation as NavigationItem[],
+        renderer.outputDirectory,
+        sidebar,
+        siteDir,
+        docsPresetPath,
+        numberPrefixParser,
+      );
     },
   );
 }

packages/docusaurus-plugin-typedoc/src/utils/get-sidebar.ts → packages/docusaurus-plugin-typedoc/src/plugin/sidebar.ts

@@ -1,7 +1,52 @@
+import * as fs from 'fs';
+import * as path from 'path';
 import { NavigationItem } from 'typedoc-plugin-markdown';
 import { Sidebar } from '../types/options.js';
+import { adjustBaseDirectory } from '../utils/adjust-basedir.js';
 
-export function getSidebar(
+export function writeSidebar(
+  navigation: NavigationItem[],
+  outputDir: string,
+  sidebar: Sidebar,
+  siteDir: string,
+  docsPresetPath: string,
+  numberPrefixParser: any,
+) {
+  if (sidebar?.autoConfiguration) {
+    const sidebarPath = path.resolve(outputDir, 'typedoc-sidebar.cjs');
+
+    let baseDir = path
+      .relative(siteDir, outputDir)
+      .split(path.sep)
+      .slice(1)
+      .join('/');
+
+    if (docsPresetPath) {
+      baseDir = adjustBaseDirectory(baseDir, docsPresetPath);
+    }
+
+    const sidebarJson = getSidebar(
+      navigation,
+      baseDir,
+      sidebar,
+      numberPrefixParser,
+    );
+
+    fs.writeFileSync(
+      sidebarPath,
+      `// @ts-check
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const typedocSidebar = { items: ${JSON.stringify(
+        sidebarJson,
+        null,
+        sidebar.pretty ? 2 : 0,
+      )}};
+module.exports = typedocSidebar.items;`,
+    );
+  }
+}
+
+function getSidebar(
   navigation: NavigationItem[],
   basePath: string,
   options: Sidebar,

packages/docusaurus-plugin-typedoc/src/plugin/typedoc.cjs

@@ -0,0 +1,31 @@
+/**
+ * Export as cjs to be compatible with esm
+ */
+module.exports = {
+  bootstrap: async (options, postRenderCallbackFn) => {
+    const typedoc = await import('typedoc');
+
+    const app = await typedoc.Application.bootstrapWithPlugins(options, [
+      new typedoc.TypeDocReader(),
+      new typedoc.PackageJsonReader(),
+      new typedoc.TSConfigReader(),
+    ]);
+
+    app.renderer.postRenderAsyncJobs.push(postRenderCallbackFn);
+
+    const project = await app.convert();
+
+    // if project is undefined typedoc has a problem - error logging will be supplied by typedoc.
+    if (!project) {
+      return;
+    }
+
+    if (options.watch) {
+      app.convertAndWatch(async (project) => {
+        await app.generateOutputs(project);
+      });
+    } else {
+      await app.generateOutputs(project);
+    }
+  },
+};