docusaurus-plugin-typedoc 1.0.0-next.22 → 1.0.0-next.24

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016 Thomas Grey
+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

package/README.md

@@ -1,270 +1,19 @@
 # docusaurus-plugin-typedoc
 
-![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=master)](https://github.com/tgreyuk/typedoc-plugin-markdown/actions/workflows/ci.yml)
+![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)
 
-A [Docusaurus](https://v2.docusaurus.io/) plugin to build TypeScript API documentation with [TypeDoc](https://github.com/TypeStrong/typedoc).
-
-## Contents
-
-- [What does it do?](#what-does-it-do)
-- [Installation](#installation)
-- [Usage](#usage)
-- [Options](#options)
-- [Sidebar](#sidebar)
-- [Other configuration](#other-configuration)
-- [License](#license)
-
-## What does it do?
-
-- Presets relevant options of [typedoc-plugin-markdown](https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/typedoc-plugin-markdown#readme).
-- Runs TypeDoc from the Docusaurus CLI.
+A Docusaurus plugin to integrate TypeDoc into a Docusaurus project.
 
 ## Installation
 
-> Install [Docusaurus](https://v2.docusaurus.io/docs/installation) in the root of your project and install the plugin dependencies in the same location as the Docusaurus website directory.
-
-> [typedoc](https://github.com/TypeStrong/typedoc) and [typedoc-plugin-markdown](https://github.com/tgreyuk/typedoc-plugin-markdown) are peer dependencies.
-
 ```shell
-npm install docusaurus-plugin-typedoc typedoc typedoc-plugin-markdown@next --save-dev
-```
-
-## Usage
-
-Add the plugin to `docusaurus.config.js` and specify the required options (see [options](#options)).
-
-```js
-module.exports = {
-  plugins: [
-    [
-      'docusaurus-plugin-typedoc',
-
-      // Plugin / TypeDoc options
-      {
-        entryPoints: ['../src/index.ts'],
-        tsconfig: '../tsconfig.json',
-      },
-    ],
-  ],
-};
-```
-
-TypeDoc will be bootstraped with the Docusaurus `start` and `build` [cli commands](https://v2.docusaurus.io/docs/cli):
-
-```javascript
-"start": "docusaurus start",
-"build": "docusaurus build",
-```
-
-Once built the docs will be available at `http://localhost:3000/docs/api` (or equivalent out directory).
-
-Typical directory structure:
-
-        ├── docusaurus-website
-            ├── build/ (static site dir)
-            ├── docs/
-            │   ├── api/ (compiled typedoc markdown)
-            ├── docusaurus.config.js
-            ├── package.json
-            ├── sidebars.js
-        ├──package.json
-        ├──src (typescript source files)
-        ├──tsconfig.json
-
-## Options
-
-### TypeDoc options
-
-Options can be declared:
-
-- Passing arguments via the command line.
-- Using a `typedoc.json` file.
-- Under the `typedocOptions` key in `tsconfig.json`.
-
-Please see <https://typedoc.org/options/configuration> for general TypeDoc option configuration.
-
-The following TypeDoc / Markdown plugin options can be passed to config:
-
-- [typedoc](https://typedoc.org/options) options (HTML specific output options that will be ignored).
-- [typedoc-plugin-markdown ](https://github.com/tgreyuk/typedoc-plugin-markdown/tree/next/packages/typedoc-plugin-markdown#options) options (Some options are already preset to target Docusaurus).
-
-The following typedoc-plugin-markdown options are preset with the plugin.
-
-```json
-{
-  "out": "./docs/api",
-  "hideInPageTOC": true,
-  "hideBreadcrumbs": true,
-  "hidePageHeader": true,
-  "entryFileName": "index.md"
-}
-```
-
-### Plugin options
-
-Options specific to the plugin should also be declared in the same object.
-
-#### `--sidebar`
-
-`sidebar.autoConfiguration`
-
-Set to `false` to disable sidebar generation. Defaults to `true`.
-
-`sidebar.filteredIds`
-
-Ids of pages to be filtered from the sidebar. This would typically be used to filter README or index pages from the sidebar.
-
-`sidebar.pretty`
-
-Pretty format the sidebar JSON.
-
-## Sidebar
-
-> Previous versions of this plugin recommended an `autogenerated` sidebar configuration. However we have decided it is more deterministic and configurable to use a manual sidebar configuration with a generated sidebar file.
-
-A docusaurus sidebar file `typedoc-sidebar.cjs` is published to the relevant output directory along with the generated markdown documentation.
-
-This file should be referenced in `sidebars.js` using a sidebar slice and can be configured in following ways:
-
-1.  Display sidebar on the root:
-
-```js
-module.exports = {
-  typedocSidebar: require('./docs/api/typedoc-sidebar.cjs'),
-};
-```
-
-2.  Display the sidebar inside a category:
-
-```js
-module.exports = {
-  typedocSidebar: {
-    'Typedoc Docs': require('./docs/api/typedoc-sidebar.js'),
-  },
-};
-```
-
-3.  Display the sidebar inside a linked category
-
-> Note the linked category page can be removed from sidebar using [`sidebar.filteredIds`]().
-
-```js
-module.exports = {
-  typedocSidebar: [
-    {
-      type: 'category',
-      label: 'Typedoc Docs',
-      link: {
-        type: 'doc',
-        id: 'api/index',
-      },
-      items: require('./docs/api/typedoc-sidebar.js'),
-    },
-  ],
-};
-```
-
-Please see <https://docusaurus.io/docs/sidebar> for sidebar documentation.
-
-## Other configuration
-
-### Navbar
-
-A navbar item can be configured in `themeConfig` options in `docusaurus.config.js`:
-
-```js
- themeConfig: {
-    navbar: {
-      items: [
-        {
-        to: 'docs/api/',  // 'api' is the 'out' directory
-        activeBasePath: 'docs',
-        label: 'API',
-        position: 'left',
-      },
-    ],
-  },
-},
-```
-
-Please see <https://docusaurus.io/docs/api/themes/configuration#navbar-items> for navbar documentation.
-
-### Multi instance
-
-It is possible to build multi TypeDoc instances by passing in multiple configs with unique ids:
-
-`docusaurus.config.js`
-
-```js
-module.exports = {
-  plugins: [
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'api-1',
-        entryPoints: ['../api-1/src/index.ts'],
-        tsconfig: '../api-1/tsconfig.json',
-        out: 'api-1',
-      },
-    ],
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'api-2',
-        entryPoints: ['../api-2/src/index.ts'],
-        tsconfig: '../api-2/tsconfig.json',
-        out: 'api-2',
-      },
-    ],
-  ],
-};
-```
-
-`sidebars.js`
-
-```js
-module.exports = {
-  typedocSidebar: {
-    'API 1': require('./docs/api-1/typedoc-sidebar.js'),
-    'API 2': require('./docs/api-2/typedoc-sidebar.js'),
-  },
-};
-```
-
-### Watch mode
-
-Watching files is supported by passing in the `watch: true` option see <https://typedoc.org/guides/options/#watch>.
-
-Targetting the option in development mode only can be achieved using Node.js Environment Variables:
-
-`package.json`
-
-```json
-"start": "TYPEDOC_WATCH=true docusaurus start",
-"build": "TYPEDOC_WATCH=false docusaurus build",
-```
-
-`docusaurus.config.js`
-
-```js
-module.exports = {
-  plugins: [
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        entryPoints: ['../src/index.ts'],
-        tsconfig: '../tsconfig.json',
-        watch: process.env.TYPEDOC_WATCH,
-      },
-    ],
-  ],
-};
-```
+  npm install docusaurus-plugin-typedoc --save-dev
+  ```
 
-### Frontmatter
+## Documentation
 
-To add frontmatter to page please use [typedoc-plugin-frontmatter](https://github.com/tgreyuk/typedoc-plugin-frontmatter#typedoc-plugin-frontmatter) and add options exposed by the plugin to the config.
+Please visit https://typedoc-plugin-markdown.org/integrations/docusaurus.
 
 ## License
 
-[MIT](https://github.com/tgreyuk/typedoc-plugin-markdown/blob/master/packages/docusaurus-plugin-typedoc/LICENSE)
+Released under the [MIT License](./LICENSE).

package/dist/options.js

@@ -8,6 +8,7 @@ const DEFAULT_PLUGIN_OPTIONS = {
     hideBreadcrumbs: true,
     hidePageHeader: true,
     entryFileName: 'index.md',
+    theme: 'docusaurus',
     sidebar: {
         autoConfiguration: true,
         pretty: false,

package/dist/plugin.d.ts

@@ -1,9 +1,8 @@
 import { PluginOptions } from '.';
-export default function pluginDocusaurus(context: any, opts: Partial<PluginOptions>): {
+export default function pluginDocusaurus(context: any, opts: Partial<PluginOptions>): Promise<{
     name: string;
-    loadContent(): Promise<void>;
     extendCli(cli: any): void;
-};
+}>;
 export declare function writeFileSync(fileName: string, data: string): void;
 export declare function normalizePath(path: string): string;
 export declare function removeDir(path: string): void;

package/dist/plugin.js

@@ -29,21 +29,21 @@ const path = __importStar(require("path"));
 const typedoc_1 = require("typedoc");
 const options_1 = require("./options");
 const sidebar_1 = require("./sidebar");
+const theme_1 = require("./theme");
 // store list of plugin ids when running multiple instances
 const apps = [];
-function pluginDocusaurus(context, opts) {
+async function pluginDocusaurus(context, opts) {
+    const PLUGIN_NAME = 'docusaurus-plugin-typedoc';
+    if (opts.id && !apps.includes(opts.id)) {
+        apps.push(opts.id);
+        await generateTypedoc(context, opts);
+    }
     return {
-        name: 'docusaurus-plugin-typedoc',
-        async loadContent() {
-            if (opts.id && !apps.includes(opts.id)) {
-                apps.push(opts.id);
-                await generateTypedoc(context, opts);
-            }
-        },
+        name: PLUGIN_NAME,
         extendCli(cli) {
             cli
                 .command('generate-typedoc')
-                .description('(docusaurus-plugin-typedoc) Generate TypeDoc docs independently of the Docusaurus build process.')
+                .description(`[${PLUGIN_NAME}] Generate TypeDoc docs independently of the Docusaurus build process.`)
                 .action(async () => {
                 var _a;
                 (_a = context.siteConfig) === null || _a === void 0 ? void 0 : _a.plugins.forEach((pluginConfig) => {
@@ -66,6 +66,7 @@ async function generateTypedoc(context, opts) {
     const options = (0, options_1.getPluginOptions)(opts);
     const { id, sidebar, ...optionsPassedToTypeDoc } = options;
     const app = await typedoc_1.Application.bootstrapWithPlugins(optionsPassedToTypeDoc);
+    app.renderer.defineTheme('docusaurus', theme_1.DocusuaurusTheme);
     const outputDir = app.options.getValue('out');
     if (options.cleanOutputDir) {
         removeDir(outputDir);

package/dist/theme.d.ts

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

@@ -0,0 +1,24 @@
+"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.typeArguments = (typeArguments) => {
+            return `\\< ${typeArguments
+                .map((typeArgument) => typeArgument instanceof typedoc_1.ReflectionType
+                ? this.reflectionType(typeArgument)
+                : this.someType(typeArgument))
+                .join(', ')} \\>`;
+        };
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-typedoc",
-  "version": "1.0.0-next.22",
-  "description": "A Docusaurus plugin to build API documentation with TypeDoc.",
+  "version": "1.0.0-next.24",
+  "description": "A Docusaurus plugin to integrate TypeDoc into a Docusaurus project.",
   "main": "dist/index.js",
   "files": [
     "dist/"
@@ -16,7 +16,7 @@
   },
   "homepage": "https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/docusaurus-plugin-typedoc",
   "peerDependencies": {
-    "typedoc-plugin-markdown": ">=4.0.0-next.28"
+    "typedoc-plugin-markdown": ">=4.0.0-next.39"
   },
   "scripts": {
     "lint": "eslint ./src --ext .ts",