docusaurus-plugin-typedoc 1.0.0-next.15 → 1.0.0-next.17

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:
 
@@ -88,12 +92,11 @@ The following typedoc-plugin-markdown options are preset with the plugin.
 
 ```json
 {
-  "out": "api",
+  "out": "./docs/api",
   "hideInPageTOC": true,
   "hideBreadcrumbs": true,
   "hidePageHeader": true,
-  "entryFileName": "index.md",
-  "includeFileNumberPrefixes": true
+  "entryFileName": "index.md"
 }
 ```
 
@@ -105,118 +108,67 @@ 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`
+Set to `false` to disable sidebar generation. Defaults to `true`.
 
-The sidebar main parent category label. Defaults to entry page title.
+`sidebar.filteredIds`
 
-`sidebar.readmeLabel`
+Ids of pages to be filtered from the sidebar. This would typically be used to filter README or index pages from the sidebar.
 
-The label of the readme page. Defaults to the h1 title of the readme page. Ignored if `readme=none`.
+`sidebar.pretty`
 
-`sidebar.indexLabel`
+Pretty format the sidebar JSON.
 
-The label of the index page. Defaults to the index page title.
+## Sidebar
 
-`sidebar.position`
+> 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.
 
-The position of the sidebar in the tree.
+A docusaurus sidebar file `typedoc-sidebar.cjs` is published to the relevant output directory along with the generated markdown documentation.
 
-#### `--docsRoot`
+This file should be referenced in `sidebars.js` using a sidebar slice and can be configured in following ways:
 
-The Docusaurus docs folder root. Use `./` if no root folder specified. Defaults to `./docs`.
-
-```shell
---docsRoot <path/to/docs-dir/>
-```
-
-### An example configuration
+1.  Display sidebar on the root:
 
 ```js
 module.exports = {
-  plugins: [
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        // TypeDoc options
-        entryPoints: ['../src/index.ts'],
-        tsconfig: '../tsconfig.json',
-        plugin: ['typedoc-plugin-xyz'],
-
-        // Plugin options
-        out: 'api-xyz',
-      },
-    ],
-  ],
+  typedocSidebar: require('./docs/api/typedoc-sidebar.cjs'),
 };
 ```
 
-## Typing the config file
-
-The config can be typed using JSDoc type annotations. See https://docusaurus.io/docs/typescript-support#typing-config.
+2.  Display the sidebar inside a category:
 
 ```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: {
+    'Typedoc Docs': require('./docs/api/typedoc-sidebar.cjs'),
+  },
+};
 ```
 
-## Recipes
-
-### Sidebar and Navbar
-
-#### Sidebar
+3.  Display the sidebar inside a linked category
 
-`sidebars.js` can be configured in following ways:
-
-1. Generate the entire sidebar from file structure of your docs folder (default behaviour):
+> Note the linked category page can be removed from sidebar using [`sidebar.filteredIds`]().
 
 ```js
 module.exports = {
-  sidebar: [
+  typedocSidebar: [
     {
-      type: 'autogenerated',
-      dirName: '.', // '.' means the docs folder
+      type: 'category',
+      label: 'Typedoc Docs',
+      link: {
+        type: 'doc',
+        id: 'api/index',
+      },
+      items: 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.
+Please see <https://docusaurus.io/docs/sidebar> for sidebar documentation.
 
-> note: `sidebar.categoryLabel` and `sidebar.position` options are ignored with this implementation)
+## Other configuration
 
-```js
-module.exports = {
-  sidebar: {
-    'Category 1': ['doc1', 'doc2', 'doc3'],
-    API: [
-      {
-        type: 'autogenerated',
-        dirName: 'api', // 'api' is the 'out' directory
-      },
-    ],
-  },
-};
-```
-
-Please see https://docusaurus.io/docs/sidebar for sidebar documentation.
-
-#### Navbar
+### Navbar
 
 A navbar item can be configured in `themeConfig` options in `docusaurus.config.js`:
 
@@ -235,7 +187,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 +220,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 +261,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/models.d.ts

@@ -1,12 +1,10 @@
 import { PluginOptions as TypedocPluginMarkdownOptions } from 'typedoc-plugin-markdown';
 export interface PluginOptions extends TypedocPluginMarkdownOptions {
     id: string;
-    docsRoot: string;
     sidebar: Partial<SidebarOptions>;
 }
 export interface SidebarOptions {
     autoConfiguration: boolean;
-    readmeLabel: string;
-    indexLabel: string;
-    categoryLabel: string;
+    pretty: boolean;
+    filteredIds: string[];
 }

package/dist/options.js

@@ -3,18 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.setOptions = exports.getPluginOptions = void 0;
 const DEFAULT_PLUGIN_OPTIONS = {
     id: 'default',
-    docsRoot: 'docs',
-    out: 'api',
+    out: './docs/api',
     hideInPageTOC: true,
     hideBreadcrumbs: true,
     hidePageHeader: true,
-    githubPages: false,
-    includeFileNumberPrefixes: true,
     entryFileName: 'index.md',
     sidebar: {
         autoConfiguration: true,
+        pretty: false,
+        filteredIds: [],
     },
-    plugin: ['typedoc-plugin-markdown', 'typedoc-plugin-frontmatter'],
+    plugin: ['typedoc-plugin-markdown'],
 };
 function getPluginOptions(opts) {
     const options = {

package/dist/plugin.d.ts

@@ -6,3 +6,4 @@ export default function pluginDocusaurus(context: any, opts: Partial<PluginOptio
 };
 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,12 +23,12 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizePath = exports.writeFileSync = void 0;
+exports.removeDir = exports.normalizePath = exports.writeFileSync = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const typedoc_1 = require("typedoc");
-const frontmatter_1 = require("./frontmatter");
 const options_1 = require("./options");
+const sidebar_1 = require("./sidebar");
 // store list of plugin ids when running multiple instances
 const apps = [];
 function pluginDocusaurus(context, opts) {
@@ -63,10 +63,31 @@ exports.default = pluginDocusaurus;
 async function generateTypedoc(context, opts) {
     const { siteDir } = context;
     const options = (0, options_1.getPluginOptions)(opts);
-    const { id, docsRoot, sidebar, ...optionsPassedToTypeDoc } = options;
-    const outputDir = path.resolve(siteDir, options.docsRoot, options.out);
+    const { id, sidebar, ...optionsPassedToTypeDoc } = options;
     const app = await typedoc_1.Application.bootstrapWithPlugins(optionsPassedToTypeDoc);
-    (0, frontmatter_1.loadFrontmatter)(app, options.sidebar);
+    const outputDir = app.options.getValue('out');
+    if (options.cleanOutputDir) {
+        removeDir(outputDir);
+    }
+    app.renderer.on(typedoc_1.PageEvent.END, (event) => {
+        var _a;
+        event.contents = (_a = event.contents) === null || _a === void 0 ? void 0 : _a.replace(/\\</g, '<');
+    });
+    if (sidebar === null || sidebar === void 0 ? void 0 : sidebar.autoConfiguration) {
+        app.renderer.postRenderAsyncJobs.push(async (output) => {
+            const sidebarPath = path.resolve(outputDir, 'typedoc-sidebar.cjs');
+            const baseDir = path
+                .relative(siteDir, outputDir)
+                .split('/')
+                .slice(1)
+                .join('/');
+            const sidebarJson = (0, sidebar_1.getSidebar)(output.navigation, baseDir, sidebar.filteredIds);
+            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();
     // if project is undefined typedoc has a problem - error logging will be supplied by typedoc.
     if (!project) {
@@ -94,3 +115,23 @@ 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, filteredIds?: string[]): any;

package/dist/sidebar.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSidebar = void 0;
+function getSidebar(navigation, basePath, filteredIds = []) {
+    return navigation
+        .map((navigationItem) => getNavigationItem(navigationItem, basePath, filteredIds))
+        .filter((navItem) => Boolean(navItem));
+}
+exports.getSidebar = getSidebar;
+function getNavigationItem(navigationItem, basePath, filteredIds) {
+    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, filteredIds),
+            ...(id && { link: { type: 'doc', id } }),
+        };
+    }
+    return id && !filteredIds.includes(id)
+        ? {
+            type: 'doc',
+            id,
+            label: navigationItem.title,
+        }
+        : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-typedoc",
-  "version": "1.0.0-next.15",
+  "version": "1.0.0-next.17",
   "description": "A Docusaurus v2 plugin to build API documentation with TypeDoc.",
   "main": "dist/index.js",
   "files": [
@@ -16,12 +16,13 @@
   },
   "homepage": "https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/docusaurus-plugin-typedoc",
   "peerDependencies": {
-    "typedoc-plugin-markdown": ">=4.0.0-next.19"
+    "typedoc-plugin-markdown": ">=4.0.0-next.22"
   },
   "scripts": {
     "lint": "eslint ./src --ext .ts",
     "prepublishOnly": "npm run lint && npm run build",
-    "build": "rm -rf ./dist && tsc"
+    "build": "rm -rf ./dist && tsc",
+    "task:docs": "node ./tasks/docs.mjs"
   },
   "author": "Thomas Grey",
   "license": "MIT",

package/dist/frontmatter.d.ts

@@ -1,3 +0,0 @@
-import { Application } from 'typedoc';
-import { SidebarOptions } from './models';
-export declare function loadFrontmatter(app: Application, sidebar: SidebarOptions): void;

package/dist/frontmatter.js

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