docusaurus-plugin-typedoc 1.3.0 → 1.4.0

package/README.md

@@ -2,11 +2,11 @@
 
 [![npm](https://img.shields.io/npm/v/docusaurus-plugin-typedoc.svg?logo=npm)](https://www.npmjs.com/package/docusaurus-plugin-typedoc) [![Build Status](https://github.com/typedoc2md/typedoc-plugin-markdown/actions/workflows/ci.docusaurus-plugin-typedoc.yml/badge.svg?branch=main&style=flat-square)](https://github.com/typedoc2md/typedoc-plugin-markdown/actions/workflows/ci.docusaurus-plugin-typedoc.yml)
 
-> A Docusaurus plugin to integrate TypeDoc ( + typedoc-plugin-markdown ) into a Docusaurus project.
+> A Docusaurus plugin to integrate TypeDoc ( + typedoc-plugin-markdown ) into the Docusaurus CLI.
 
 ## Documentation
 
-Please visit the [https://typedoc-plugin-markdown.org/plugins/docusaurus](https://typedoc-plugin-markdown.org/plugins/docusaurus) for comprehensive documentation, including options and usage guides.
+Please visit [https://typedoc-plugin-markdown.org/plugins/docusaurus](https://typedoc-plugin-markdown.org/plugins/docusaurus) for comprehensive documentation, including options and usage guides.
 
 ## License
 

package/dist/index.d.ts

@@ -1,5 +1,2 @@
-/**
- * @module core
- */
-export { PluginOptions } from './models.js';
-export { default } from './plugin/docusaurus.js';
+export { default } from './plugin.js';
+export { PluginOptions } from './types/index.js';

package/dist/index.js

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

package/dist/options.d.ts

@@ -0,0 +1,3 @@
+import { TypeDocOptions } from 'typedoc';
+import { PluginOptions } from './types/plugin.js';
+export declare function getPluginOptions(context: any, opts: Partial<PluginOptions & TypeDocOptions>): Record<string, any>;

package/dist/options.js

@@ -0,0 +1,22 @@
+import * as path from 'path';
+export function getPluginOptions(context, opts) {
+    const docsPreset = context.siteConfig?.presets?.find((preset) => Boolean(preset[1]?.docs));
+    const docsPresetPath = docsPreset
+        ? docsPreset[1]?.docs?.path || './docs'
+        : './docs';
+    const options = {
+        out: './docs/api',
+        docsPath: path.join(context.siteDir, docsPresetPath),
+        numberPrefixParser: docsPreset
+            ? (docsPreset[1]?.docs?.numberPrefixParser ?? true)
+            : true,
+        ...opts,
+        plugin: [
+            ...new Set([
+                ...['typedoc-plugin-markdown', 'typedoc-docusaurus-theme'],
+                ...(opts.plugin || []),
+            ]),
+        ],
+    };
+    return options;
+}

package/dist/plugin.d.ts

@@ -0,0 +1,7 @@
+import { TypeDocOptions } from 'typedoc';
+import { Cli, LoadContext } from './types/index.js';
+import { PluginOptions } from './types/plugin.js';
+export default function pluginDocusaurus(context: LoadContext, opts: Partial<PluginOptions & TypeDocOptions>): Promise<{
+    name: string;
+    extendCli(cli: Cli): void;
+}>;

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

@@ -1,6 +1,5 @@
 import * as fs from 'fs';
-import { getPluginOptions } from '../options/options.js';
-import { writeSidebar } from './sidebar.js';
+import { getPluginOptions } from './options.js';
 export default async function pluginDocusaurus(context, opts) {
     await generateTypedoc(context, opts);
     return {
@@ -10,7 +9,7 @@ export default async function pluginDocusaurus(context, opts) {
                 .command('generate-typedoc')
                 .description(`[docusaurus-plugin-typedoc] Generate TypeDoc docs independently of the Docusaurus build process.`)
                 .action(async () => {
-                context.siteConfig?.plugins.forEach((pluginConfig) => {
+                context.siteConfig?.plugins?.forEach((pluginConfig) => {
                     // Check PluginConfig is typed to [string, PluginOptions]
                     if (pluginConfig && typeof pluginConfig[1] === 'object') {
                         generateTypedoc(context, pluginConfig[1]);
@@ -26,17 +25,13 @@ export default async function pluginDocusaurus(context, opts) {
 async function generateTypedoc(context, opts) {
     // get plugin options
     const options = getPluginOptions(context, opts);
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { id, ...typedocOptions } = options;
     // create outDir if it doesn't exist
-    if (!fs.existsSync(options.out)) {
-        fs.mkdirSync(options.out, { recursive: true });
+    if (!fs.existsSync(typedocOptions.out)) {
+        fs.mkdirSync(typedocOptions.out, { recursive: true });
     }
-    // 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);
-    });
+    // Bootstrap typedoc with options (this mimics the TypeDoc CLI)
+    const typedoc = await import('./typedoc.cjs');
+    await typedoc.bootstrap(typedocOptions);
 }

package/dist/{plugin/typedoc.cjs → typedoc.cjs}

@@ -1,8 +1,15 @@
+// @ts-check
+
 /**
- * Export as cjs to be compatible with esm
+ * Export as CJS to ensure a fully synchronous module cache.
+ *
+ * This prevents "plugin loaded multiple times" errors when Docusaurus triggers a recompile.
  */
 module.exports = {
-  bootstrap: async (options, postRenderCallbackFn) => {
+  bootstrap: async (
+    /** @type {import('typedoc').TypeDocOptions} */
+    options,
+  ) => {
     const typedoc = await import('typedoc');
 
     const app = await typedoc.Application.bootstrapWithPlugins(options, [
@@ -11,8 +18,6 @@ module.exports = {
       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.

package/dist/types/docusaurus.d.ts

@@ -0,0 +1,13 @@
+export interface LoadContext {
+    siteDir: string;
+    siteConfig: {
+        plugins?: any[];
+        presets?: any[];
+    };
+}
+export type Cli = {
+    command(name: string): Cli;
+    description(desc: string): Cli;
+    option(flag: string, desc?: string): Cli;
+    action(fn: (...args: any[]) => void): void;
+};

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 /**
- * All plugin types are exported from this module.
+ * All plugin types are exported from here.
  *
  * @module
  */
-export * from './options.js';
+export * from './docusaurus.js';
+export * from './plugin.js';

package/dist/types/index.js

@@ -1,6 +1,7 @@
 /**
- * All plugin types are exported from this module.
+ * All plugin types are exported from here.
  *
  * @module
  */
-export * from './options.js';
+export * from './docusaurus.js';
+export * from './plugin.js';

package/dist/{models.d.ts → types/plugin.d.ts}

@@ -1,6 +1,4 @@
+import { PluginOptions as TypedocDocusaurusThemeOptions } from 'typedoc-docusaurus-theme';
 import { PluginOptions as TypedocPluginMarkdownOptions } from 'typedoc-plugin-markdown';
-import { PluginOptions as DocusaurusOptions } from './types/index.js';
-export interface PluginOptions extends TypedocPluginMarkdownOptions, DocusaurusOptions {
-    id: string;
-    out: string;
+export interface PluginOptions extends TypedocPluginMarkdownOptions, TypedocDocusaurusThemeOptions {
 }

package/dist/types/plugin.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-typedoc",
-  "version": "1.3.0",
-  "description": "A Docusaurus plugin to integrate TypeDoc ( + typedoc-plugin-markdown ) into a Docusaurus project.",
+  "version": "1.4.0",
+  "description": "A Docusaurus plugin to integrate TypeDoc ( + typedoc-plugin-markdown ) into the Docusaurus CLI.",
   "exports": {
     ".": "./dist/index.js"
   },
@@ -18,27 +18,26 @@
     "directory": "packages/docusaurus-plugin-typedoc"
   },
   "homepage": "http://typedoc-plugin-markdown.org/plugins/docusaurus",
-  "peerDependencies": {
-    "typedoc-plugin-markdown": ">=4.6.0"
-  },
   "scripts": {
     "lint": "eslint ./src",
-    "prebuild": "rm -rf dist && prebuild-options && copyfiles --up 1 ./src/**/*.cjs ./dist/",
+    "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",
-    "test": "jest",
-    "test:update": "npm run build && npm test -- -u"
+    "pretest": "cd ../../devtools/examples/docusaurus-ts && npm i && npm run generate",
+    "test": "node ./test/test.mjs",
+    "build-and-test": "npm run build && npm test"
   },
   "author": "Thomas Grey",
   "license": "MIT",
+  "peerDependencies": {
+    "typedoc-plugin-markdown": ">=4.6.0"
+  },
+  "dependencies": {
+    "typedoc-docusaurus-theme": "^1.4.0"
+  },
   "keywords": [
     "docusaurus",
     "typedoc",
     "plugin"
-  ],
-  "devDependencies": {
-    "@docusaurus/core": "^3.7.0",
-    "@docusaurus/types": "^3.7.0"
-  }
+  ]
 }

package/dist/options/declarations.d.ts

@@ -1,22 +0,0 @@
-import { DeclarationOption } from 'typedoc';
-/**
- * **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. 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](/plugins/docusaurus/guides/sidebar) for additional information on sidebar setup.
- *
- */
-export declare const sidebar: Partial<DeclarationOption>;

package/dist/options/declarations.js

@@ -1,36 +0,0 @@
-import { ParameterType } from 'typedoc';
-import { DEFAULT_SIDEBAR_OPTIONS } from './options.js';
-/**
- * **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. 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](/plugins/docusaurus/guides/sidebar) for additional information on sidebar setup.
- *
- */
-export const sidebar = {
-    help: 'Configures the autogenerated Docusaurus sidebar.',
-    type: ParameterType.Mixed,
-    defaultValue: DEFAULT_SIDEBAR_OPTIONS,
-    validate(value) {
-        if (typeof value !== 'object') {
-            console.warn('[typedoc-plugin-markdown] Sidebar must be an object.');
-        }
-        const invalidKeys = Object.keys(value).filter((key) => !Object.keys(DEFAULT_SIDEBAR_OPTIONS).includes(key));
-        if (invalidKeys.length > 0) {
-            console.warn(`[typedoc-plugin-markdown] Invalid keys in sidebar options: ${invalidKeys.join(', ')}`);
-        }
-    },
-};

package/dist/options/index.d.ts

@@ -1,7 +0,0 @@
-/**
- * All plugin types are exported from this module.
- *
- * @module
- */
-export * as declarations from './declarations.js';
-export * as presets from './presets.js';

package/dist/options/index.js

@@ -1,7 +0,0 @@
-/**
- * All plugin types are exported from this module.
- *
- * @module
- */
-export * as declarations from './declarations.js';
-export * as presets from './presets.js';

package/dist/options/options.d.ts

@@ -1,7 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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 = {
-    ...presets,
-    id: 'default',
-    sidebar: {
-        ...DEFAULT_SIDEBAR_OPTIONS,
-    },
-};
-export function getPluginOptions(context, opts) {
-    const docsPreset = context.siteConfig?.presets?.find((preset) => Boolean(preset[1]?.docs));
-    const options = {
-        ...DEFAULT_PLUGIN_OPTIONS,
-        siteDir: context.siteDir,
-        docsPresetPath: docsPreset ? docsPreset[1]?.docs?.path : null,
-        numberPrefixParser: docsPreset
-            ? docsPreset[1]?.docs?.numberPrefixParser
-            : null,
-        ...opts,
-        sidebar: {
-            ...DEFAULT_PLUGIN_OPTIONS.sidebar,
-            ...opts.sidebar,
-        },
-        plugin: [
-            ...new Set([...['typedoc-plugin-markdown'], ...(opts.plugin || [])]),
-        ],
-    };
-    return options;
-}

package/dist/options/presets.d.ts

@@ -1,7 +0,0 @@
-export declare const presets: {
-    plugin: string[];
-    out: string;
-    hideBreadcrumbs: boolean;
-    hidePageHeader: boolean;
-    entryFileName: string;
-};

package/dist/options/presets.js

@@ -1,7 +0,0 @@
-export const presets = {
-    plugin: ['typedoc-plugin-markdown', 'docusaurus-plugin-typedoc'],
-    out: './docs/api',
-    hideBreadcrumbs: true,
-    hidePageHeader: true,
-    entryFileName: 'index.md',
-};

package/dist/plugin/docusaurus.d.ts

@@ -1,5 +0,0 @@
-import { PluginOptions } from '../models.js';
-export default function pluginDocusaurus(context: any, opts: Partial<PluginOptions>): Promise<{
-    name: string;
-    extendCli(cli: any): void;
-}>;

package/dist/plugin/sidebar.d.ts

@@ -1,3 +0,0 @@
-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

@@ -1,83 +0,0 @@
-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/types/options.d.ts

@@ -1,15 +0,0 @@
-/**
- * Describes the options declared by the plugin.
- */
-export interface PluginOptions {
-    /**
-     * Configures the autogenerated Docusaurus sidebar.
-     */
-    sidebar?: Sidebar;
-}
-export interface Sidebar {
-    autoConfiguration: boolean;
-    pretty: boolean;
-    typescript: boolean;
-    deprecatedItemClassName: string;
-}

package/dist/types/options.js

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

package/dist/utils/adjust-basedir.d.ts

@@ -1,4 +0,0 @@
-/**
- * This method is designed to resolve the base directory paths for documentation presets.
- */
-export declare function adjustBaseDirectory(originalPath: string, subPath: string): string;

package/dist/utils/adjust-basedir.js

@@ -1,28 +0,0 @@
-import * as path from 'path';
-/**
- * This method is designed to resolve the base directory paths for documentation presets.
- */
-export function adjustBaseDirectory(originalPath, subPath) {
-    // Normalize the paths to handle different path formats and OS differences
-    originalPath = path.normalize(originalPath);
-    subPath = path.normalize(subPath);
-    // Split the original path into an array of segments
-    const segments = originalPath.split(path.sep);
-    // Split the sub path into an array of segments and filter out ".." to handle relative paths
-    const subSegments = subPath
-        .split(path.sep)
-        .filter((segment) => segment !== '..');
-    // Find the index of the first sub path segment in the original path segments
-    const startIndex = segments.indexOf(subSegments[0]);
-    // Remove the sub path segments from the original path segments if found
-    if (startIndex !== -1) {
-        segments.splice(startIndex, subSegments.length);
-    }
-    // Join the segments back into a path and remove the leading slash if present
-    let newPath = segments.join(path.sep);
-    // Ensure there is no leading slash
-    if (newPath.startsWith(path.sep)) {
-        newPath = newPath.slice(1);
-    }
-    return newPath.replace(/\\/g, '/');
-}