docusaurus-plugin-typedoc 1.0.0-next.14 → 1.0.0-next.16

package/README.md

@@ -1,21 +1,29 @@
 # 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)
+
 A [Docusaurus](https://v2.docusaurus.io/) plugin to build TypeScript API documentation with [TypeDoc](https://github.com/TypeStrong/typedoc).
 
-[![npm](https://img.shields.io/npm/v/docusaurus-plugin-typedoc.svg)](https://www.npmjs.com/package/docusaurus-plugin-typedoc)
-![CI](https://github.com/tgreyuk/typedoc-plugin-markdown/actions/workflows/ci.yml/badge.svg?branch=master)
+## 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.
-- Adds some basic frontmatter to pages and exposes the ability to configure frontmatter further.
 
 ## 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), [typedoc-plugin-markdown](https://github.com/tgreyuk/typedoc-plugin-markdown) are peer dependencies.
+> [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
@@ -23,8 +31,6 @@ npm install docusaurus-plugin-typedoc typedoc typedoc-plugin-markdown@next --sav
 
 ## Usage
 
-### Config
-
 Add the plugin to `docusaurus.config.js` and specify the required options (see [options](#options)).
 
 ```js
@@ -50,34 +56,32 @@ TypeDoc will be bootstraped with the Docusaurus `start` and `build` [cli command
 "build": "docusaurus build",
 ```
 
-Once built the docs will be available at `/docs/api` (or equivalent out directory).
+Once built the docs will be available at `http://localhost:3000/docs/api` (or equivalent out directory).
 
-### Directory structure
+Typical directory structure:
 
-```
-├── docusauruss-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
-```
+        ├── 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.
-
-### TypeDoc options
+Please see <https://typedoc.org/options/configuration> for general TypeDoc option configuration.
 
 The following TypeDoc / Markdown plugin options can be passed to config:
 
@@ -92,8 +96,7 @@ The following typedoc-plugin-markdown options are preset with the plugin.
   "hideInPageTOC": true,
   "hideBreadcrumbs": true,
   "hidePageHeader": true,
-  "entryFileName": "index.md",
-  "includeFileNumberPrefixes": true
+  "entryFileName": "index.md"
 }
 ```
 
@@ -105,23 +108,15 @@ Options specific to the plugin should also be declared in the same object.
 
 `sidebar.autoConfiguration`
 
-Set to `false` to disable sidebar metadata added to frontmatter. Defaults to `true`.
-
-`sidebar.categoryLabel`
-
-The sidebar main parent category label. Defaults to entry page title.
-
-`sidebar.readmeLabel`
+Set to `false` to disable sidebar generation. Defaults to `true`.
 
-The label of the readme page. Defaults to the h1 title of the readme page. Ignored if `readme=none`.
+`sidebar.filteredIds`
 
-`sidebar.indexLabel`
+Ids of pages to be filtered from the sidebar. This would typically be used to filter README or modules named index from the sidebar.
 
-The label of the index page. Defaults to the index page title.
+`sidebar.pretty`
 
-`sidebar.position`
-
-The position of the sidebar in the tree.
+Pretty format the sidebar json
 
 #### `--docsRoot`
 
@@ -131,92 +126,57 @@ The Docusaurus docs folder root. Use `./` if no root folder specified. Defaults
 --docsRoot <path/to/docs-dir/>
 ```
 
-### An example configuration
+## Sidebar
 
-```js
-module.exports = {
-  plugins: [
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        // TypeDoc options
-        entryPoints: ['../src/index.ts'],
-        tsconfig: '../tsconfig.json',
-        plugin: ['typedoc-plugin-xyz'],
+> 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.
 
-        // Plugin options
-        out: 'api-xyz',
-      },
-    ],
-  ],
-};
-```
+A docusaurus sidebar file `typedoc-sidebar.cjs` is published to the relevant output directory along with the generated markdown documentation.
 
-## Typing the config file
+This file should be referenced in `sidebars.js` using a sidebar slice and can be configured in following ways:
 
-The config can be typed using JSDoc type annotations. See https://docusaurus.io/docs/typescript-support#typing-config.
+1.  Display sidebar on the root:
 
 ```js
-/** @type {import('docusaurus-plugin-typedoc').PluginOptions} */
-```
-
-## Frontmatter
-
-Additional frontmatter options can be added to the config. Please see [typedoc-plugin-frontmatter](https://github.com/tgreyuk/typedoc-plugin-frontmatter#typedoc-plugin-frontmatter).
-
-For example:
-
-```json
-{
-  "frontmatterGlobals": {
-    "pagination_prev": null,
-    "pagination_next": null
-  }
-}
+module.exports = {
+  typedocSidebar: require('./docs/api/typedoc-sidebar.cjs'),
+};
 ```
 
-## Recipes
-
-### Sidebar and Navbar
-
-#### Sidebar
-
-`sidebars.js` can be configured in following ways:
-
-1. Generate the entire sidebar from file structure of your docs folder (default behaviour):
+2.  Display the sidebar inside a category:
 
 ```js
 module.exports = {
-  sidebar: [
-    {
-      type: 'autogenerated',
-      dirName: '.', // '.' means the docs folder
-    },
-  ],
+  typedocSidebar: {
+    'Typedoc Docs': require('./docs/api/typedoc-sidebar.cjs'),
+  },
 };
 ```
 
-2. Alternatively, if you wish to manually control other parts of your sidebar you can use a slice for the TypeDoc sidebar.
+3.  Display the sidebar inside a linked category
 
-> note: `sidebar.categoryLabel` and `sidebar.position` options are ignored with this implementation)
+> Note the linked category page can be removed from sidebar using [`sidebar.filteredIds`]().
 
 ```js
 module.exports = {
-  sidebar: {
-    'Category 1': ['doc1', 'doc2', 'doc3'],
-    API: [
-      {
-        type: 'autogenerated',
-        dirName: 'api', // 'api' is the 'out' directory
+  typedocSidebar: [
+    {
+      type: 'category',
+      label: 'Typedoc Docs',
+      link: {
+        type: 'doc',
+        id: 'api/index',
       },
-    ],
-  },
+      items: require('./docs/api/typedoc-sidebar.cjs'),
+    },
+  ],
 };
 ```
 
-Please see https://docusaurus.io/docs/sidebar for sidebar documentation.
+Please see <https://docusaurus.io/docs/sidebar> for sidebar documentation.
+
+## Other configuration
 
-#### Navbar
+### Navbar
 
 A navbar item can be configured in `themeConfig` options in `docusaurus.config.js`:
 
@@ -235,7 +195,7 @@ A navbar item can be configured in `themeConfig` options in `docusaurus.config.j
 },
 ```
 
-Please see https://docusaurus.io/docs/api/themes/configuration#navbar-items for navbar documentation.
+Please see <https://docusaurus.io/docs/api/themes/configuration#navbar-items> for navbar documentation.
 
 ### Multi instance
 
@@ -268,9 +228,20 @@ module.exports = {
 };
 ```
 
+`sidebars.js`
+
+```js
+module.exports = {
+  typedocSidebar: {
+    'API 1': require('./docs/api-1/typedoc-sidebar.cjs'),
+    'API 2': require('./docs/api-2/typedoc-sidebar.cjs'),
+  },
+};
+```
+
 ### Watch mode
 
-Watching files is supported by passing in the `watch: true` option see [https://typedoc.org/guides/options/#watch](https://typedoc.org/guides/options/#watch).
+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:
 
@@ -298,6 +269,10 @@ module.exports = {
 };
 ```
 
+### Frontmatter
+
+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.
+
 ## License
 
 [MIT](https://github.com/tgreyuk/typedoc-plugin-markdown/blob/master/packages/docusaurus-plugin-typedoc/LICENSE)

package/dist/options.d.ts

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

package/dist/options.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadOptions = exports.getPluginOptions = void 0;
-const typedoc_1 = require("typedoc");
+exports.setOptions = exports.getPluginOptions = void 0;
 const DEFAULT_PLUGIN_OPTIONS = {
     id: 'default',
     docsRoot: 'docs',
@@ -9,12 +8,11 @@ const DEFAULT_PLUGIN_OPTIONS = {
     hideInPageTOC: true,
     hideBreadcrumbs: true,
     hidePageHeader: true,
-    githubPages: false,
-    includeFileNumberPrefixes: true,
     entryFileName: 'index.md',
     sidebar: {
         autoConfiguration: true,
     },
+    plugin: ['typedoc-plugin-markdown'],
 };
 function getPluginOptions(opts) {
     const options = {
@@ -24,34 +22,16 @@ function getPluginOptions(opts) {
             ...DEFAULT_PLUGIN_OPTIONS.sidebar,
             ...opts.sidebar,
         },
+        plugin: [
+            ...new Set([...DEFAULT_PLUGIN_OPTIONS.plugin, ...(opts.plugin || [])]),
+        ],
     };
     return options;
 }
 exports.getPluginOptions = getPluginOptions;
-function loadOptions(app) {
-    app.options.addReader(new typedoc_1.PackageJsonReader());
-    app.options.addReader(new typedoc_1.TypeDocReader());
-    app.options.addReader(new typedoc_1.TSConfigReader());
-    app.options.addDeclaration({
-        name: 'sidebar',
-        type: typedoc_1.ParameterType.Mixed,
-    });
-    app.options.addReader(new (class {
-        constructor() {
-            this.name = 'docusaurus-options';
-            this.order = 900;
-            this.supportsPackages = false;
-        }
-        read(container) {
-            const requiredPlugins = [
-                'typedoc-plugin-markdown',
-                'typedoc-plugin-frontmatter',
-            ];
-            const plugins = container.getValue('plugin');
-            container.setValue('plugin', [
-                ...new Set([...requiredPlugins, ...plugins]),
-            ]);
-        }
-    })());
+function setOptions(app, options) {
+    for (const [key, val] of Object.entries(options)) {
+        app.options.setValue(key, val);
+    }
 }
-exports.loadOptions = loadOptions;
+exports.setOptions = setOptions;

package/dist/plugin.d.ts

@@ -4,3 +4,6 @@ export default function pluginDocusaurus(context: any, opts: Partial<PluginOptio
     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

@@ -23,10 +23,12 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeDir = exports.normalizePath = exports.writeFileSync = void 0;
+const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const typedoc_1 = require("typedoc");
 const options_1 = require("./options");
-const renderer_1 = require("./renderer");
+const sidebar_1 = require("./sidebar");
 // store list of plugin ids when running multiple instances
 const apps = [];
 function pluginDocusaurus(context, opts) {
@@ -61,13 +63,25 @@ exports.default = pluginDocusaurus;
 async function generateTypedoc(context, opts) {
     const { siteDir } = context;
     const options = (0, options_1.getPluginOptions)(opts);
-    const { id, docsRoot, ...optionsPassedToTypeDoc } = options;
+    const { id, docsRoot, sidebar, ...optionsPassedToTypeDoc } = options;
     const outputDir = path.resolve(siteDir, options.docsRoot, options.out);
-    const app = new typedoc_1.Application();
-    (0, options_1.loadOptions)(app);
-    (0, renderer_1.loadRenderer)(app);
-    await app.bootstrapWithPlugins(optionsPassedToTypeDoc);
-    const project = app.convert();
+    if (options.cleanOutputDir) {
+        removeDir(outputDir);
+    }
+    const app = await typedoc_1.Application.bootstrapWithPlugins(optionsPassedToTypeDoc);
+    app.renderer.on(typedoc_1.PageEvent.END, (event) => {
+        var _a;
+        event.contents = (_a = event.contents) === null || _a === void 0 ? void 0 : _a.replace(/\\</g, '<');
+    });
+    app.renderer.postRenderAsyncJobs.push(async (output) => {
+        const sidebarPath = path.resolve(outputDir, 'typedoc-sidebar.cjs');
+        const sidebarJson = (0, sidebar_1.getSidebar)(output.navigation, options.out);
+        fs.writeFileSync(sidebarPath, `// @ts-check
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const typedocSidebar = { items: ${JSON.stringify(sidebarJson)}};
+module.exports = typedocSidebar.items;`);
+    });
+    const project = await app.convert();
     // if project is undefined typedoc has a problem - error logging will be supplied by typedoc.
     if (!project) {
         if (app.options.getValue('skipErrorChecking')) {
@@ -85,3 +99,32 @@ async function generateTypedoc(context, opts) {
         await app.generateDocs(project, outputDir);
     }
 }
+function writeFileSync(fileName, data) {
+    fs.mkdirSync(path.dirname(normalizePath(fileName)), { recursive: true });
+    fs.writeFileSync(normalizePath(fileName), data);
+}
+exports.writeFileSync = writeFileSync;
+function normalizePath(path) {
+    return path.replace(/\\/g, '/');
+}
+exports.normalizePath = normalizePath;
+function removeDir(path) {
+    if (fs.existsSync(path)) {
+        const files = fs.readdirSync(path);
+        if (files.length > 0) {
+            files.forEach(function (filename) {
+                if (fs.statSync(path + '/' + filename).isDirectory()) {
+                    removeDir(path + '/' + filename);
+                }
+                else {
+                    fs.unlinkSync(path + '/' + filename);
+                }
+            });
+            fs.rmdirSync(path);
+        }
+        else {
+            fs.rmdirSync(path);
+        }
+    }
+}
+exports.removeDir = removeDir;

package/dist/sidebar.d.ts

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

package/dist/sidebar.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSidebar = void 0;
+function getSidebar(navigation, basePath) {
+    return navigation
+        .map((navigationItem) => {
+        return getNavigationItem(navigationItem, basePath);
+    })
+        .filter((navItem) => Boolean(navItem));
+}
+exports.getSidebar = getSidebar;
+function getNavigationItem(navigationItem, basePath) {
+    var _a;
+    const id = navigationItem.url
+        ? `${basePath}/${navigationItem.url}`.replace(/(.*).md/, '$1')
+        : null;
+    if ((_a = navigationItem.children) === null || _a === void 0 ? void 0 : _a.length) {
+        return {
+            type: 'category',
+            label: navigationItem.title,
+            items: getSidebar(navigationItem.children, basePath),
+            ...(id && { link: { type: 'doc', id } }),
+        };
+    }
+    return id
+        ? {
+            type: 'doc',
+            id,
+            label: navigationItem.title,
+        }
+        : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-typedoc",
-  "version": "1.0.0-next.14",
+  "version": "1.0.0-next.16",
   "description": "A Docusaurus v2 plugin to build API documentation with TypeDoc.",
   "main": "dist/index.js",
   "files": [
@@ -15,17 +15,14 @@
     "directory": "packages/docusaurus-plugin-typedoc"
   },
   "homepage": "https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/docusaurus-plugin-typedoc",
-  "dependencies": {
-    "typedoc-plugin-frontmatter": ">=0.0.2"
-  },
   "peerDependencies": {
-    "typedoc-plugin-markdown": ">=4.0.0-next.18"
+    "typedoc-plugin-markdown": ">=4.0.0-next.21"
   },
   "scripts": {
     "lint": "eslint ./src --ext .ts",
     "prepublishOnly": "npm run lint && npm run build",
     "build": "rm -rf ./dist && tsc",
-    "demo": "npm run build && cd demo && npm run start"
+    "task:docs": "node ./tasks/docs.mjs"
   },
   "author": "Thomas Grey",
   "license": "MIT",
@@ -36,5 +33,8 @@
     "markdown",
     "typescript",
     "api"
-  ]
+  ],
+  "dependencies": {
+    "@docusaurus/types": "^2.4.1"
+  }
 }

package/dist/renderer.d.ts

@@ -1,2 +0,0 @@
-import { Application } from 'typedoc';
-export declare function loadRenderer(app: Application): void;

package/dist/renderer.js

@@ -1,66 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadRenderer = void 0;
-const typedoc_plugin_frontmatter_1 = require("typedoc-plugin-frontmatter");
-function loadRenderer(app) {
-    app.renderer.on(typedoc_plugin_frontmatter_1.FrontmatterEvent.PREPARE_FRONTMATTER, (event) => {
-        loadFrontmatter(app, event);
-    });
-}
-exports.loadRenderer = loadRenderer;
-function loadFrontmatter(app, event) {
-    var _a, _b, _c, _d, _e, _f, _g;
-    const hasReadme = !app.options.getValue('readme').endsWith('none');
-    const entryPage = app.options.getValue('entryFileName');
-    const indexPage = app.options.getValue('indexFileName');
-    const sidebar = app.options.getValue('sidebar');
-    const model = (_a = event.page) === null || _a === void 0 ? void 0 : _a.model;
-    const sidebarLabel = model === null || model === void 0 ? void 0 : model.name;
-    let pluginFrontmatter = {};
-    if (sidebar.autoConfiguration) {
-        if (((_b = event.page) === null || _b === void 0 ? void 0 : _b.url) === app.options.getValue('entryFileName')) {
-            if (sidebar.categoryLabel) {
-                pluginFrontmatter = {
-                    ...pluginFrontmatter,
-                    sidebar_label: sidebar.categoryLabel,
-                };
-            }
-        }
-        if (hasReadme) {
-            if (((_c = event.page) === null || _c === void 0 ? void 0 : _c.url) === entryPage) {
-                pluginFrontmatter = {
-                    ...pluginFrontmatter,
-                    ...(sidebar.readmeLabel && { sidebar_label: sidebar.readmeLabel }),
-                    sidebar_position: 0,
-                };
-            }
-            if (((_d = event.page) === null || _d === void 0 ? void 0 : _d.url) === `01-${indexPage}`) {
-                pluginFrontmatter = {
-                    ...pluginFrontmatter,
-                    ...(sidebar.indexLabel && { sidebar_label: sidebar.indexLabel }),
-                };
-            }
-        }
-        else {
-            if (((_e = event.page) === null || _e === void 0 ? void 0 : _e.url) === entryPage) {
-                pluginFrontmatter = {
-                    ...pluginFrontmatter,
-                    ...(sidebar.indexLabel && { sidebar_label: sidebar.indexLabel }),
-                    sidebar_position: 0,
-                };
-            }
-        }
-        // Add sidebar labels to all pages
-        if (!(((_f = event.page) === null || _f === void 0 ? void 0 : _f.url) === entryPage) &&
-            !(((_g = event.page) === null || _g === void 0 ? void 0 : _g.url) === `01-${indexPage}`)) {
-            pluginFrontmatter = {
-                ...pluginFrontmatter,
-                sidebar_label: sidebarLabel,
-            };
-        }
-    }
-    event.frontmatter = {
-        ...pluginFrontmatter,
-        ...event.frontmatter,
-    };
-}