docusaurus-plugin-typedoc 1.0.0-next.27 → 1.0.0-next.29

package/README.md

@@ -1,6 +1,6 @@
 # docusaurus-plugin-typedoc
 
-![npm](https://img.shields.io/npm/v/docusaurus-plugin-typedoc%2Fnext?&logo=npm) ![Downloads](https://img.shields.io/npm/dm/docusaurus-plugin-typedoc) [![Build Status](https://github.com/tgreyuk/typedoc-plugin-markdown/actions/workflows/ci.yml/badge.svg?branch=next)](https://github.com/tgreyuk/typedoc-plugin-markdown/actions/workflows/ci.yml)
+![npm](https://img.shields.io/npm/v/docusaurus-plugin-typedoc%2Fnext?&logo=npm) [![Build Status](https://github.com/tgreyuk/typedoc-plugin-markdown/actions/workflows/ci.yml/badge.svg?branch=next)](https://github.com/tgreyuk/typedoc-plugin-markdown/actions/workflows/ci.yml)
 
 A Docusaurus plugin to integrate TypeDoc into a Docusaurus project.
 
@@ -12,8 +12,4 @@ A Docusaurus plugin to integrate TypeDoc into a Docusaurus project.
 
 ## Documentation
 
-Please visit https://typedoc-plugin-markdown.org/integrations/docusaurus.
-
-## License
-
-Released under the [MIT License](./LICENSE).
+Please visit [typedoc-plugin-markdown.org](https://typedoc-plugin-markdown.org/plugins/docusaurus) for comprehensive documentation, including options and usage guides.

package/dist/models.d.ts

@@ -1,10 +1,5 @@
 import { PluginOptions as TypedocPluginMarkdownOptions } from 'typedoc-plugin-markdown';
-export interface PluginOptions extends TypedocPluginMarkdownOptions {
+import { PluginOptions as DocusaurusOptions } from './options/option-types';
+export interface PluginOptions extends TypedocPluginMarkdownOptions, DocusaurusOptions {
     id: string;
-    sidebar: Partial<SidebarOptions>;
-}
-export interface SidebarOptions {
-    autoConfiguration: boolean;
-    pretty: boolean;
-    filteredIds: string[];
 }

package/dist/options/declarations.d.ts

@@ -0,0 +1,36 @@
+import { ParameterType } from 'typedoc';
+/**
+ *
+ * > *In addition to the sidebar options listed below, you can configure the structure of the sidebar by utilizing the TypeDoc [`navigation options`](https://typedoc.org/options/output/#navigation) `includeGroups`, `includeCategories` and `includeFolders`*.
+ *
+ * **sidebar.autoConfiguration**
+ *
+ * Set to `false` to disable sidebar generation. Defaults to `true`.
+ *
+ * **sidebar.pretty**
+ *
+ * Pretty format the sidebar JSON.
+ *
+ * Please see the [sidebar guide](/plugins/docusaurus/guide/sidebar) for additional information on sidebar setup.
+ *
+ * ```json filename="Example"
+ * "navigation": {
+ *   "includeGroups": true,
+ *   "includeCategories": true
+ * },
+ * "sidebar": {
+ *   "pretty": true
+ * }
+ * ```
+ *
+ * @omitExample
+ *
+ */
+export declare const sidebar: {
+    help: string;
+    type: ParameterType;
+    defaultValue: {
+        autoConfiguration: boolean;
+        pretty: boolean;
+    };
+};

package/dist/options/declarations.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sidebar = void 0;
+const typedoc_1 = require("typedoc");
+const options_1 = require("../options");
+/**
+ *
+ * > *In addition to the sidebar options listed below, you can configure the structure of the sidebar by utilizing the TypeDoc [`navigation options`](https://typedoc.org/options/output/#navigation) `includeGroups`, `includeCategories` and `includeFolders`*.
+ *
+ * **sidebar.autoConfiguration**
+ *
+ * Set to `false` to disable sidebar generation. Defaults to `true`.
+ *
+ * **sidebar.pretty**
+ *
+ * Pretty format the sidebar JSON.
+ *
+ * Please see the [sidebar guide](/plugins/docusaurus/guide/sidebar) for additional information on sidebar setup.
+ *
+ * ```json filename="Example"
+ * "navigation": {
+ *   "includeGroups": true,
+ *   "includeCategories": true
+ * },
+ * "sidebar": {
+ *   "pretty": true
+ * }
+ * ```
+ *
+ * @omitExample
+ *
+ */
+exports.sidebar = {
+    help: 'Configures the autogenerated Docusaurus sidebar.',
+    type: typedoc_1.ParameterType.Mixed,
+    defaultValue: options_1.DEFAULT_SIDEBAR_OPTIONS,
+};

package/dist/options/option-types.d.ts

@@ -0,0 +1,26 @@
+import { ManuallyValidatedOption } from 'typedoc';
+declare module 'typedoc' {
+    interface TypeDocOptionMap {
+        sidebar: ManuallyValidatedOption<Sidebar>;
+    }
+}
+/**
+ * Describes the options declared by the plugin.
+ *
+ * @category Options
+ */
+export interface PluginOptions {
+    /**
+     * Configures the autogenerated Docusaurus sidebar.
+     */
+    sidebar: Sidebar;
+}
+/**
+ *
+ *
+ * @category Options
+ */
+export interface Sidebar {
+    autoConfiguration: boolean;
+    pretty: boolean;
+}

package/dist/options/option-types.js

@@ -0,0 +1,3 @@
+"use strict";
+// THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/options/presets.d.ts

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

package/dist/options/presets.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = {
+    out: './docs/api',
+    hideBreadcrumbs: true,
+    hidePageHeader: true,
+    entryFileName: 'index.md',
+    plugin: ['typedoc-plugin-markdown'],
+};

package/dist/options.d.ts

@@ -1,3 +1,5 @@
-import { Application } from 'typedoc';
+export declare const DEFAULT_SIDEBAR_OPTIONS: {
+    autoConfiguration: boolean;
+    pretty: boolean;
+};
 export declare function getPluginOptions(opts: Record<string, any>): Record<string, any>;
-export declare function setOptions(app: Application, options: any): void;

package/dist/options.js

@@ -1,19 +1,20 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setOptions = exports.getPluginOptions = void 0;
+exports.getPluginOptions = exports.DEFAULT_SIDEBAR_OPTIONS = void 0;
+const presets_1 = __importDefault(require("./options/presets"));
+exports.DEFAULT_SIDEBAR_OPTIONS = {
+    autoConfiguration: true,
+    pretty: false,
+};
 const DEFAULT_PLUGIN_OPTIONS = {
+    ...presets_1.default,
     id: 'default',
-    out: './docs/api',
-    hideBreadcrumbs: true,
-    hidePageHeader: true,
-    entryFileName: 'index.md',
-    theme: 'docusaurus',
     sidebar: {
-        autoConfiguration: true,
-        pretty: false,
-        filteredIds: [],
+        ...exports.DEFAULT_SIDEBAR_OPTIONS,
     },
-    plugin: ['typedoc-plugin-markdown'],
 };
 function getPluginOptions(opts) {
     const options = {
@@ -30,9 +31,3 @@ function getPluginOptions(opts) {
     return options;
 }
 exports.getPluginOptions = getPluginOptions;
-function setOptions(app, options) {
-    for (const [key, val] of Object.entries(options)) {
-        app.options.setValue(key, val);
-    }
-}
-exports.setOptions = setOptions;

package/dist/plugin.js

@@ -27,8 +27,8 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const typedoc_1 = require("typedoc");
 const options_1 = require("./options");
+const options = __importStar(require("./options/declarations"));
 const sidebar_1 = require("./sidebar");
-const theme_1 = require("./theme");
 // store list of plugin ids when running multiple instances
 const apps = [];
 async function pluginDocusaurus(context, opts) {
@@ -60,30 +60,34 @@ exports.default = pluginDocusaurus;
  */
 async function generateTypedoc(context, opts) {
     const { siteDir } = context;
-    const options = (0, options_1.getPluginOptions)(opts);
-    const { id, sidebar, ...optionsPassedToTypeDoc } = options;
+    const pluginOpions = (0, options_1.getPluginOptions)(opts);
+    const { id, sidebar, ...optionsPassedToTypeDoc } = pluginOpions;
     const app = await typedoc_1.Application.bootstrapWithPlugins(optionsPassedToTypeDoc);
-    app.renderer.defineTheme('docusaurus', theme_1.DocusuaurusTheme);
-    const outputDir = app.options.getValue('out');
-    if (context.siteConfig?.markdown?.format !== 'mdx') {
-        app.renderer.on(typedoc_1.PageEvent.END, (event) => {
-            event.contents = event.contents?.replace(/\\</g, '<');
+    Object.entries(options).forEach(([name, option]) => {
+        app.options.addDeclaration({
+            name,
+            ...option,
         });
-    }
+    });
+    const outputDir = app.options.getValue('out');
     if (sidebar?.autoConfiguration) {
         const docsPreset = context.siteConfig?.presets?.find((preset) => Boolean(preset[1]?.docs));
         app.renderer.postRenderAsyncJobs.push(async (output) => {
-            const sidebarPath = path.resolve(outputDir, 'typedoc-sidebar.cjs');
-            const baseDir = path
-                .relative(siteDir, outputDir)
-                .split(path.sep)
-                .slice(1)
-                .join(path.sep);
-            const sidebarJson = (0, sidebar_1.getSidebar)(output.navigation, baseDir, sidebar.filteredIds, docsPreset ? docsPreset[1]?.docs?.numberPrefixParser : null);
-            fs.writeFileSync(sidebarPath, `// @ts-check
+            if (output.navigation) {
+                const sidebarPath = path.resolve(outputDir, 'typedoc-sidebar.cjs');
+                const sidebarJSONPath = path.resolve(outputDir, 'typedoc-sidebar.json');
+                fs.writeFileSync(sidebarJSONPath, JSON.stringify(output.navigation, null, 2));
+                const baseDir = path
+                    .relative(siteDir, outputDir)
+                    .split(path.sep)
+                    .slice(1)
+                    .join(path.sep);
+                const sidebarJson = (0, sidebar_1.getSidebar)(output.navigation, baseDir, docsPreset ? docsPreset[1]?.docs?.numberPrefixParser : null);
+                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;`);
+            }
         });
     }
     const project = await app.convert();
@@ -93,7 +97,7 @@ module.exports = typedocSidebar.items;`);
             return;
         }
         console.error('[docusaurus-plugin-typedoc] TypeDoc exited with an error. Use the "skipErrorChecking" option to disable TypeDoc error checking.');
-        process.exit();
+        process.exit(1);
     }
     if (app.options.getValue('watch')) {
         app.convertAndWatch(async (project) => {

package/dist/sidebar.d.ts

@@ -1,2 +1,2 @@
 import { NavigationItem } from 'typedoc-plugin-markdown';
-export declare function getSidebar(navigation: NavigationItem[], basePath: string, filteredIds?: string[], numberPrefixParser?: any): any;
+export declare function getSidebar(navigation: NavigationItem[], basePath: string, numberPrefixParser?: any): any;

package/dist/sidebar.js

@@ -1,16 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSidebar = void 0;
-function getSidebar(navigation, basePath, filteredIds = [], numberPrefixParser) {
+function getSidebar(navigation, basePath, numberPrefixParser) {
     return navigation
-        .map((navigationItem) => getNavigationItem(navigationItem, basePath, filteredIds, numberPrefixParser))
+        .map((navigationItem) => getNavigationItem(navigationItem, basePath, numberPrefixParser))
         .filter((navItem) => Boolean(navItem));
 }
 exports.getSidebar = getSidebar;
-function getNavigationItem(navigationItem, basePath, filteredIds, numberPrefixParser) {
+function getNavigationItem(navigationItem, basePath, numberPrefixParser) {
     const parsedUrl = numberPrefixParser === false
-        ? navigationItem.url
-        : navigationItem.url?.replace(/\d+\-/g, '');
+        ? navigationItem.path
+        : navigationItem.path?.replace(/\d+\-/g, '');
     const getId = () => {
         const idParts = [];
         if (basePath.length > 0) {
@@ -19,8 +19,8 @@ function getNavigationItem(navigationItem, basePath, filteredIds, numberPrefixPa
         if (parsedUrl) {
             idParts.push(parsedUrl);
         }
-        if (navigationItem.url) {
-            return idParts.join('/').replace(/(.*).md/, '$1');
+        if (navigationItem.path) {
+            return idParts.join('/').replace(/(.*)\.\w+$/, '$1');
         }
         return null;
     };
@@ -28,16 +28,21 @@ function getNavigationItem(navigationItem, basePath, filteredIds, numberPrefixPa
     if (navigationItem.children?.length) {
         return {
             type: 'category',
-            label: navigationItem.title,
-            items: getSidebar(navigationItem.children, basePath, filteredIds, numberPrefixParser),
-            ...(id && { link: { type: 'doc', id } }),
+            label: `${navigationItem.title}`,
+            items: getSidebar(navigationItem.children, basePath, numberPrefixParser),
+            ...(id && {
+                link: {
+                    type: 'doc',
+                    id,
+                },
+            }),
         };
     }
-    return id && !filteredIds.includes(id)
+    return id
         ? {
             type: 'doc',
             id,
-            label: navigationItem.title,
+            label: `${navigationItem.title}`,
         }
         : null;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-typedoc",
-  "version": "1.0.0-next.27",
-  "description": "A Docusaurus plugin to integrate TypeDoc into a Docusaurus project.",
+  "version": "1.0.0-next.29",
+  "description": "A Docusaurus plugin to integrate TypeDoc ( + typedoc-plugin-markdown ) into a Docusaurus project.",
   "main": "dist/index.js",
   "files": [
     "dist/"
@@ -20,8 +20,9 @@
   },
   "scripts": {
     "lint": "eslint ./src --ext .ts",
+    "prebuild": "rm -rf dist && prebuild-options",
     "prepublishOnly": "npm run lint && npm run build",
-    "build": "rm -rf ./dist && tsc",
+    "build": "tsc",
     "pretest": "rm -rf ./test/out && docusaurus generate-typedoc",
     "test": "jest",
     "test:update": "npm run build && npm test -- -u"
@@ -37,7 +38,7 @@
     "api"
   ],
   "devDependencies": {
-    "@docusaurus/core": "^3.1.1",
-    "@docusaurus/types": "^3.1.1"
+    "@docusaurus/core": "^3.2.1",
+    "@docusaurus/types": "^3.2.1"
   }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 Thomas Grey
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/dist/theme.d.ts

@@ -1,5 +0,0 @@
-import { Reflection } from 'typedoc';
-import { MarkdownPageEvent, MarkdownTheme } from 'typedoc-plugin-markdown';
-export declare class DocusuaurusTheme extends MarkdownTheme {
-    getRenderContext(pageEvent: MarkdownPageEvent<Reflection>): any;
-}

package/dist/theme.js

@@ -1,27 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DocusuaurusTheme = void 0;
-const typedoc_1 = require("typedoc");
-const typedoc_plugin_markdown_1 = require("typedoc-plugin-markdown");
-class DocusuaurusTheme extends typedoc_plugin_markdown_1.MarkdownTheme {
-    getRenderContext(pageEvent) {
-        return new DocusuaurusThemeThemeRenderContext(this, pageEvent, this.application.options);
-    }
-}
-exports.DocusuaurusTheme = DocusuaurusTheme;
-class DocusuaurusThemeThemeRenderContext extends typedoc_plugin_markdown_1.MarkdownThemeRenderContext {
-    constructor() {
-        super(...arguments);
-        // adds space around type arguments as docusaurus generates broken links without it in certain use-cases (see https://github.com/facebook/docusaurus/issues/9518)
-        this.partials = {
-            ...this.partials,
-            typeArguments: (typeArguments) => {
-                return `\\< ${typeArguments
-                    .map((typeArgument) => typeArgument instanceof typedoc_1.ReflectionType
-                    ? this.partials.reflectionType(typeArgument)
-                    : this.partials.someType(typeArgument))
-                    .join(', ')} \\>`;
-            },
-        };
-    }
-}