docusaurus-plugin-typedoc 1.2.2 → 1.3.0

package/dist/index.d.ts

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

package/dist/index.js

@@ -1 +1 @@
-export { default } from './plugins/docusaurus.js';
+export { default } from './plugin/docusaurus.js';

package/dist/options/declarations.d.ts

@@ -1,26 +1,22 @@
 import { DeclarationOption } from 'typedoc';
-/**
- * Used internally to pass options from docusaurus.config to TypeDoc.
- *
- * @internal
- *
- * @hidden
- */
-export declare const docusaurusConfigOptions: Partial<DeclarationOption>;
 /**
  * **autoConfiguration**
  *
  * Set to `false` to disable sidebar generation. Defaults to `true`.
  *
+ * **typescript**
+ *
+ * Set to `true` to generate a TypeScript file. Defaults to `false` (CommonJs).
+ *
  * **pretty**
  *
- * Pretty format the sidebar JSON.
+ * Pretty format the sidebar JSON. Defaults to `false`.
  *
  * **deprecatedItemClassName**
  *
  * The class name to apply to deprecated items in the sidebar. Defaults to `"typedoc-sidebar-item-deprecated"`.
  *
- * Please see the [sidebar guide](https:/typedoc-plugin-markdown.org/plugins/docusaurus/sidebar) for additional information on sidebar setup.
+ * Please see the [sidebar guide](/plugins/docusaurus/guides/sidebar) for additional information on sidebar setup.
  *
  */
 export declare const sidebar: Partial<DeclarationOption>;

package/dist/options/declarations.js

@@ -1,31 +1,23 @@
 import { 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 = {
-    help: 'docusaurus.config options - should not be used if running as a docusaurus plugin.',
-    type: ParameterType.String,
-    defaultValue: '{}',
-};
 /**
  * **autoConfiguration**
  *
  * Set to `false` to disable sidebar generation. Defaults to `true`.
  *
+ * **typescript**
+ *
+ * Set to `true` to generate a TypeScript file. Defaults to `false` (CommonJs).
+ *
  * **pretty**
  *
- * Pretty format the sidebar JSON.
+ * Pretty format the sidebar JSON. Defaults to `false`.
  *
  * **deprecatedItemClassName**
  *
  * The class name to apply to deprecated items in the sidebar. Defaults to `"typedoc-sidebar-item-deprecated"`.
  *
- * Please see the [sidebar guide](https:/typedoc-plugin-markdown.org/plugins/docusaurus/sidebar) for additional information on sidebar setup.
+ * Please see the [sidebar guide](/plugins/docusaurus/guides/sidebar) for additional information on sidebar setup.
  *
  */
 export const sidebar = {

package/dist/options/options.d.ts

@@ -1,6 +1,7 @@
 export declare const DEFAULT_SIDEBAR_OPTIONS: {
     autoConfiguration: boolean;
     pretty: boolean;
+    typescript: boolean;
     deprecatedItemClassName: string;
 };
 export declare function getPluginOptions(context: any, opts: Record<string, any>): Record<string, any>;

package/dist/options/options.js

@@ -2,6 +2,7 @@ import { presets } from './presets.js';
 export const DEFAULT_SIDEBAR_OPTIONS = {
     autoConfiguration: true,
     pretty: false,
+    typescript: false,
     deprecatedItemClassName: 'typedoc-sidebar-item-deprecated',
 };
 const DEFAULT_PLUGIN_OPTIONS = {
@@ -26,10 +27,7 @@ export function getPluginOptions(context, opts) {
             ...opts.sidebar,
         },
         plugin: [
-            ...new Set([
-                ...['typedoc-plugin-markdown', 'docusaurus-plugin-typedoc/typedoc'],
-                ...(opts.plugin || []),
-            ]),
+            ...new Set([...['typedoc-plugin-markdown'], ...(opts.plugin || [])]),
         ],
     };
     return options;

package/dist/{plugins → plugin}/docusaurus.js

@@ -1,8 +1,6 @@
-import { spawnSync } from 'child_process';
 import * as fs from 'fs';
-import * as path from 'path';
 import { getPluginOptions } from '../options/options.js';
-import { presets } from '../options/presets.js';
+import { writeSidebar } from './sidebar.js';
 export default async function pluginDocusaurus(context, opts) {
     await generateTypedoc(context, opts);
     return {
@@ -26,19 +24,19 @@ export default async function pluginDocusaurus(context, opts) {
  * Initiates a new typedoc Application bootstrapped with plugin options
  */
 async function generateTypedoc(context, opts) {
+    // 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
-    const typedocExecutable = process.platform === 'win32' ? 'typedoc.cmd' : 'typedoc';
-    spawnSync(typedocExecutable, [
-        ...plugin.flatMap((plugin) => ['--plugin', plugin]),
-        '--docusaurusConfigOptions',
-        `${JSON.stringify(options)}`,
-    ], {
-        stdio: 'inherit',
+    // configure options for typedoc
+    const { 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    id, siteDir, numberPrefixParser, docsPresetPath, sidebar, ...optionsPassedToTypeDoc } = options;
+    const typeDocApp = await import('./typedoc.cjs');
+    // bootstrap typedoc with options
+    await typeDocApp.bootstrap(optionsPassedToTypeDoc, async (renderer) => {
+        writeSidebar(renderer.navigation, renderer.outputDirectory, sidebar, siteDir, docsPresetPath, numberPrefixParser);
     });
 }

package/dist/plugin/sidebar.d.ts

@@ -0,0 +1,3 @@
+import { NavigationItem } from 'typedoc-plugin-markdown';
+import { Sidebar } from '../types/options.js';
+export declare function writeSidebar(navigation: NavigationItem[], outputDir: string, sidebar: Sidebar, siteDir: string, docsPresetPath: string, numberPrefixParser: any): void;

package/dist/plugin/sidebar.js

@@ -0,0 +1,83 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { adjustBaseDirectory } from '../utils/adjust-basedir.js';
+export function writeSidebar(navigation, outputDir, sidebar, siteDir, docsPresetPath, numberPrefixParser) {
+    if (sidebar?.autoConfiguration) {
+        const sidebarFileName = sidebar.typescript
+            ? 'typedoc-sidebar.ts'
+            : 'typedoc-sidebar.cjs';
+        const sidebarPath = path.resolve(outputDir, sidebarFileName);
+        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);
+        const sidebarContent = sidebar.typescript
+            ? getTypescriptSidebar(sidebarJson, sidebar)
+            : getJsSidebar(sidebarJson, sidebar);
+        fs.writeFileSync(sidebarPath, sidebarContent);
+    }
+}
+function getTypescriptSidebar(sidebarJson, sidebar) {
+    return `import { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+const typedocSidebar: SidebarsConfig = { items: ${JSON.stringify(sidebarJson, null, sidebar.pretty ? 2 : 0)}};
+export default typedocSidebar;`;
+}
+function getJsSidebar(sidebarJson, sidebar) {
+    return `// @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, basePath, options, numberPrefixParser) {
+    return navigation
+        .map((navigationItem) => getNavigationItem(navigationItem, basePath, options, numberPrefixParser))
+        .filter((navItem) => Boolean(navItem));
+}
+function getNavigationItem(navigationItem, basePath, options, numberPrefixParser) {
+    const navigationItemPath = navigationItem.path || navigationItem.url;
+    const parsedUrl = numberPrefixParser === false
+        ? navigationItemPath
+        : navigationItemPath?.replace(/\d+-/g, '');
+    const getId = () => {
+        const idParts = [];
+        if (basePath.length > 0) {
+            idParts.push(basePath);
+        }
+        if (parsedUrl) {
+            idParts.push(parsedUrl.replace(/\\/g, '/'));
+        }
+        if (navigationItemPath) {
+            return idParts.join('/').replace(/(.*)\.\w+$/, '$1');
+        }
+        return null;
+    };
+    const id = getId();
+    if (navigationItem.children?.length) {
+        return {
+            type: 'category',
+            label: navigationItem.title,
+            items: getSidebar(navigationItem.children, basePath, options, numberPrefixParser),
+            ...(id && {
+                link: {
+                    type: 'doc',
+                    id,
+                },
+            }),
+        };
+    }
+    return id
+        ? {
+            type: 'doc',
+            id,
+            label: navigationItem.title,
+            ...(navigationItem.isDeprecated && {
+                className: options.deprecatedItemClassName,
+            }),
+        }
+        : null;
+}

package/dist/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);
+    }
+  },
+};

package/dist/types/options.d.ts

@@ -2,17 +2,14 @@
  * Describes the options declared by the plugin.
  */
 export interface PluginOptions {
-    /**
-     * docusaurus.config options - should not be used if running as a docusaurus plugin.
-     */
-    docusaurusConfigOptions: string;
     /**
      * Configures the autogenerated Docusaurus sidebar.
      */
-    sidebar: Sidebar;
+    sidebar?: Sidebar;
 }
 export interface Sidebar {
     autoConfiguration: boolean;
     pretty: boolean;
+    typescript: boolean;
     deprecatedItemClassName: string;
 }

package/dist/types/options.js

@@ -1 +1,4 @@
+/*
+ * THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY
+ */
 export {};

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "docusaurus-plugin-typedoc",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "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": [
@@ -20,11 +19,11 @@
   },
   "homepage": "http://typedoc-plugin-markdown.org/plugins/docusaurus",
   "peerDependencies": {
-    "typedoc-plugin-markdown": ">=4.4.0"
+    "typedoc-plugin-markdown": ">=4.6.0"
   },
   "scripts": {
     "lint": "eslint ./src",
-    "prebuild": "rm -rf dist && prebuild-options",
+    "prebuild": "rm -rf dist && prebuild-options && 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"
   }
 }

package/dist/plugins/typedoc.d.ts

@@ -1,2 +0,0 @@
-import { MarkdownApplication } from 'typedoc-plugin-markdown';
-export declare function load(app: MarkdownApplication): void;

package/dist/plugins/typedoc.js

@@ -1,56 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import * as options from '../options/declarations.js';
-import { adjustBaseDirectory } from '../utils/adjust-basedir.js';
-import { getSidebar } from '../utils/get-sidebar.js';
-export function load(app) {
-    Object.entries(options).forEach(([name, option]) => {
-        app.options.addDeclaration({
-            name,
-            ...option,
-        });
-    });
-    app.options.addReader(new (class {
-        name = 'docusaurus-options';
-        order = 100;
-        supportsPackages = false;
-        read(container) {
-            const presets = JSON.parse(container.getValue('docusaurusConfigOptions'));
-            const ignoreKeys = [
-                'id',
-                'siteDir',
-                'docsPresetPath',
-                'numberPrefixParser',
-            ];
-            Object.entries(presets)
-                .filter(([key]) => !ignoreKeys.includes(key))
-                .forEach(([key, value]) => {
-                container.setValue(key, value);
-            });
-        }
-    })());
-    app.renderer.postRenderAsyncJobs.push(async (output) => {
-        const outputDir = app.options.getValue('out');
-        const docusaurusConfigOptions = JSON.parse(app.options.getValue('docusaurusConfigOptions'));
-        const sidebar = app.options.getValue('sidebar');
-        const siteDir = docusaurusConfigOptions.siteDir;
-        const docsPresetPath = docusaurusConfigOptions.docsPresetPath;
-        const numberPrefixParser = docusaurusConfigOptions.numberPrefixParser;
-        if (sidebar?.autoConfiguration && output.navigation) {
-            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(output.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;`);
-        }
-    });
-}

package/dist/utils/get-sidebar.d.ts

@@ -1,3 +0,0 @@
-import { NavigationItem } from 'typedoc-plugin-markdown';
-import { Sidebar } from '../types/options.js';
-export declare function getSidebar(navigation: NavigationItem[], basePath: string, options: Sidebar, numberPrefixParser?: any): any;

package/dist/utils/get-sidebar.js

@@ -1,48 +0,0 @@
-export function getSidebar(navigation, basePath, options, numberPrefixParser) {
-    return navigation
-        .map((navigationItem) => getNavigationItem(navigationItem, basePath, options, numberPrefixParser))
-        .filter((navItem) => Boolean(navItem));
-}
-function getNavigationItem(navigationItem, basePath, options, numberPrefixParser) {
-    const navigationItemPath = navigationItem.path || navigationItem.url;
-    const parsedUrl = numberPrefixParser === false
-        ? navigationItemPath
-        : navigationItemPath?.replace(/\d+-/g, '');
-    const getId = () => {
-        const idParts = [];
-        if (basePath.length > 0) {
-            idParts.push(basePath);
-        }
-        if (parsedUrl) {
-            idParts.push(parsedUrl.replace(/\\/g, '/'));
-        }
-        if (navigationItemPath) {
-            return idParts.join('/').replace(/(.*)\.\w+$/, '$1');
-        }
-        return null;
-    };
-    const id = getId();
-    if (navigationItem.children?.length) {
-        return {
-            type: 'category',
-            label: navigationItem.title,
-            items: getSidebar(navigationItem.children, basePath, options, numberPrefixParser),
-            ...(id && {
-                link: {
-                    type: 'doc',
-                    id,
-                },
-            }),
-        };
-    }
-    return id
-        ? {
-            type: 'doc',
-            id,
-            label: navigationItem.title,
-            ...(navigationItem.isDeprecated && {
-                className: options.deprecatedItemClassName,
-            }),
-        }
-        : null;
-}