docusaurus-plugin-typedoc - npm Package Compare versions

Comparing version 1.3.1 to 1.4.0

dist/options.d.ts

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

dist/options.js

+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;
+}

dist/plugin.d.ts

+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;
+}>;

dist/plugin.js

+import * as fs from 'fs';
+import { getPluginOptions } from './options.js';
+export default async function pluginDocusaurus(context, opts) {
+    await generateTypedoc(context, opts);
+    return {
+        name: 'docusaurus-plugin-typedoc',
+        extendCli(cli) {
+            cli
+                .command('generate-typedoc')
+                .description(`[docusaurus-plugin-typedoc] Generate TypeDoc docs independently of the Docusaurus build process.`)
+                .action(async () => {
+                context.siteConfig?.plugins?.forEach((pluginConfig) => {
+                    // Check PluginConfig is typed to [string, PluginOptions]
+                    if (pluginConfig && typeof pluginConfig[1] === 'object') {
+                        generateTypedoc(context, pluginConfig[1]);
+                    }
+                });
+            });
+        },
+    };
+}
+/**
+ * Initiates a new typedoc Application bootstrapped with plugin options
+ */
+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(typedocOptions.out)) {
+        fs.mkdirSync(typedocOptions.out, { recursive: true });
+    }
+    // Bootstrap typedoc with options (this mimics the TypeDoc CLI)
+    const typedoc = await import('./typedoc.cjs');
+    await typedoc.bootstrap(typedocOptions);
+}

dist/typedoc.cjs

+// @ts-check
+
+/**
+ * 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 (
+    /** @type {import('typedoc').TypeDocOptions} */
+    options,
+  ) => {
+    const typedoc = await import('typedoc');
+
+    const app = await typedoc.Application.bootstrapWithPlugins(options, [
+      new typedoc.TypeDocReader(),
+      new typedoc.PackageJsonReader(),
+      new typedoc.TSConfigReader(),
+    ]);
+
+    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);
+    }
+  },
+};

dist/types/docusaurus.d.ts

+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;
+};

dist/types/docusaurus.js

+export {};

dist/types/plugin.d.ts

+import { PluginOptions as TypedocDocusaurusThemeOptions } from 'typedoc-docusaurus-theme';
+import { PluginOptions as TypedocPluginMarkdownOptions } from 'typedoc-plugin-markdown';
+export interface PluginOptions extends TypedocPluginMarkdownOptions, TypedocDocusaurusThemeOptions {
+}

dist/types/plugin.js

+export {};

dist/index.d.ts

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

dist/index.js

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

dist/types/index.d.ts

 /**
- * 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';

dist/types/index.js

 /**
- * 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.json

 {
   "name": "docusaurus-plugin-typedoc",
-  "version": "1.3.1",
-  "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": {
@@ -21,15 +21,19 @@ ".": "./dist/index.js"
   "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",
-    "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": [
@@ -36,0 +40,0 @@ "docusaurus",

README.md

@@ -5,3 +5,3 @@ # docusaurus-plugin-typedoc
 
-> 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.
 
@@ -8,0 +8,0 @@ ## Documentation

dist/models.d.ts

-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;
-}

dist/models.js

-export {};

dist/options/declarations.d.ts

-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.
- *
- * ```js  filename="docusaurus.config.js"
- * {
- *   plugins: [
- *     [
- *       'docusaurus-plugin-typedoc',
- *       {
- *         "sidebar": {
- *           "autoConfiguration": true,
- *           "pretty": false,
- *           "typescript": false,
- *           "deprecatedItemClassName": "typedoc-sidebar-item-deprecated"
- *         }
- *       }
- *     ]
- *   ]
- * }
- *
- * @omitExample
- *
- */
-export declare const sidebar: Partial<DeclarationOption>;

dist/options/declarations.js

-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.
- *
- * ```js  filename="docusaurus.config.js"
- * {
- *   plugins: [
- *     [
- *       'docusaurus-plugin-typedoc',
- *       {
- *         "sidebar": {
- *           "autoConfiguration": true,
- *           "pretty": false,
- *           "typescript": false,
- *           "deprecatedItemClassName": "typedoc-sidebar-item-deprecated"
- *         }
- *       }
- *     ]
- *   ]
- * }
- *
- * @omitExample
- *
- */
-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(', ')}`);
-        }
-    },
-};

dist/options/index.d.ts

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

dist/options/index.js

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

dist/options/options.d.ts

-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>;

dist/options/options.js

-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;
-}

dist/options/presets.d.ts

-export declare const presets: {
-    plugin: string[];
-    out: string;
-    hideBreadcrumbs: boolean;
-    hidePageHeader: boolean;
-    entryFileName: string;
-};

dist/options/presets.js

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

dist/plugin/docusaurus.d.ts

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

dist/plugin/docusaurus.js

-import * as fs from 'fs';
-import { getPluginOptions } from '../options/options.js';
-import { writeSidebar } from './sidebar.js';
-export default async function pluginDocusaurus(context, opts) {
-    await generateTypedoc(context, opts);
-    return {
-        name: 'docusaurus-plugin-typedoc',
-        extendCli(cli) {
-            cli
-                .command('generate-typedoc')
-                .description(`[docusaurus-plugin-typedoc] Generate TypeDoc docs independently of the Docusaurus build process.`)
-                .action(async () => {
-                context.siteConfig?.plugins.forEach((pluginConfig) => {
-                    // Check PluginConfig is typed to [string, PluginOptions]
-                    if (pluginConfig && typeof pluginConfig[1] === 'object') {
-                        generateTypedoc(context, pluginConfig[1]);
-                    }
-                });
-            });
-        },
-    };
-}
-/**
- * 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
-    if (!fs.existsSync(options.out)) {
-        fs.mkdirSync(options.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);
-    });
-}

dist/plugin/sidebar.d.ts

-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;

dist/plugin/sidebar.js

-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);
-        const baseDir = adjustBaseDirectory(path.relative(siteDir, outputDir).split(path.sep).join('/'), docsPresetPath || 'docs');
-        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;
-}

dist/plugin/typedoc.cjs

-/**
- * 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);
-    }
-  },
-};

dist/types/options.d.ts

-/**
- * 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;
-}

dist/types/options.js

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

dist/utils/adjust-basedir.d.ts

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

dist/utils/adjust-basedir.js

-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, '/');
-}

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Fixed alerts

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Improved metrics

Number of low supply chain risk alerts

1

-66.67%

Worsened metrics

Total package byte prevSize

6698

-55.93%

Dependency count

2

100%

Number of package files

15

-40%

Lines of code

136

-65.39%

Number of medium supply chain risk alerts

1

Infinity%

Dependency changes

• + Added

  typedoc-docusaurus-theme@^1.4.0

• + Added

  typedoc-docusaurus-theme@1.4.2
  (transitive)