docusaurus-plugin-typedoc 0.16.1 → 0.16.5

package/README.md

@@ -7,14 +7,11 @@ A [Docusaurus v2](https://v2.docusaurus.io/) plugin to build documentation with
 
 ## What it does?
 
-- Generates static TypeDoc pages in Markdown as part of the build.
-- Adds frontmatter to pages.
+Generates static TypeDoc pages in Markdown with frontmatter as part of the Docusaurus build.
 
 ## Installation
 
-> Install in the same location as the Docusaurus website directory.
-
-This guide assumes that a Docusaurus project has already been setup. See [installation docs](https://v2.docusaurus.io/docs/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.
 
 ```shell
 npm install typedoc typedoc-plugin-markdown docusaurus-plugin-typedoc --save-dev
@@ -49,61 +46,23 @@ 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.
-
-```
-website/ (docusaururs website root)
-├── build/ (static site dir)
-├── docs/
-│   ├── api/ (compiled typedoc markdown)
-├── docusaurus.config.js
-├── package.json
-├── sidebars.js
-```
-
-### Sidebar
-
-`sidebars.js` can be configured in following ways:
+Once built the docs will be available at `/docs/api` (or equivalent out directory).
 
-1 ) Generate the entire sidebar from file structure of your docs folder (default behaviour):
+### Directory structure
 
-```js
-module.exports = {
-  someSidebar: [
-    {
-      type: 'autogenerated',
-      dirName: '.', // '.' means the docs folder
-    },
-  ],
-};
 ```
-
-2 ) Alternatively, if you wish to manually control other parts of your sidebar you can use a slice for the TypeDoc sidebar.
-(note:`sidebar.categoryLabel` and `sidebar.position` options are ignored with this implementation)
-
-
-```js
-module.exports = {
-  someSidebar: {
-    'Category 1': ['doc1', 'doc2', 'doc3'],
-
-    // use seperate generated file
-    'API': require('./typedoc-sidebar.js'),
-
-    // or write inline
-    'API': [
-      {
-        type: 'autogenerated',
-        dirName: 'api', // 'api' is the 'out' directory
-      },
-    ],
-  },
-};
+├── 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
 ```
 
-> To maintain backward compatibility with previous versions a `./typedoc-sidebar.js` is created by default. Pass `sidebar.sidebarFile:null` to prevent this.
-
-Please see https://docusaurus.io/docs/sidebar for sidebar documentation.
 
 ## Options
 
@@ -131,18 +90,18 @@ TypeDoc options can also be declared:
 - Using a `typedoc.json` file.
 - Under the `typedocOptions` key in `tsconfig.json`.
 
-Note: Options declared in this manner will take priority and overwrite options declared in `docusaurus.config.js`.
+> Note: Options declared in this manner will take priority and overwrite options declared in `docusaurus.config.js`.
 
 ### Plugin options
 
-| Name                    | Default | Description                                  |
-| :---------------------- | :------ | :------------------------------------------- |
-| `out`                   | `"api"` | Output directory relative to docs directory. |
-| `sidebar.categoryLabel` | `API`   | The sidebar parent category label.           |
-| `sidebar.fullNames`     | `false` | Display full names with module path.         |
-| `sidebar.position`      | `null`  | The position of the sidebar in the tree.     |
+Options specific to the plugin should also be declared in the same object.
 
-If the manual sidebar is not required pass `sidebar.sidebarFile: null` to skip sidebar generation.
+| Name                    | Default | Description                                              |
+| :---------------------- | :------ | :------------------------------------------------------- |
+| `out`                   | `"api"` | Output dir relative to docs dir (use `.` for no subdir). |  |
+| `sidebar.categoryLabel` | `API`   | The sidebar parent category label.                       |
+| `sidebar.fullNames`     | `false` | Display full names with module path.                     |
+| `sidebar.position`      | `auto`  | The position of the sidebar in the tree.                 |
 
 ### An example configuration
 
@@ -172,7 +131,68 @@ module.exports = {
 ```
 
 
-## Additional config
+## 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):
+
+```js
+module.exports = {
+  sidebar: [
+    {
+      type: 'autogenerated',
+      dirName: '.', // '.' means the docs folder
+    },
+  ],
+};
+```
+
+2) Alternatively, if you wish to manually control other parts of your sidebar you can use a slice for the TypeDoc sidebar.
+
+> note: `sidebar.categoryLabel` and `sidebar.position` options are ignored with this implementation)
+
+```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
+
+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
 
@@ -232,6 +252,27 @@ module.exports = {
 };
 ```
 
+### Monorepo setup
+
+`docusaurus.config.js`
+
+```js
+module.exports = {
+  plugins: [
+    [
+      'docusaurus-plugin-typedoc',
+      {
+        entryPoints: ['../packages/package-a', '../packages/package-b'],
+        entryPointStrategy: 'packages',
+        sidebar: {
+          fullNames: true
+        },
+      },
+    ],
+  ],
+};
+```
+
 ## License
 
 [MIT](https://github.com/tgreyuk/typedoc-plugin-markdown/blob/master/packages/docusaurus-plugin-typedoc/LICENSE)

package/dist/options.d.ts

@@ -1,3 +1,2 @@
 import { PluginOptions } from './types';
 export declare const getPluginOptions: (opts: Partial<PluginOptions>) => PluginOptions;
-export declare const getOutputDirectory: (siteDir: string, options: PluginOptions) => string;

package/dist/options.js

@@ -1,44 +1,24 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getOutputDirectory = exports.getPluginOptions = void 0;
-const path = __importStar(require("path"));
+exports.getPluginOptions = void 0;
 const DEFAULT_PLUGIN_OPTIONS = {
     id: 'default',
     docsRoot: 'docs',
     out: 'api',
     sidebar: {
         fullNames: false,
-        sidebarFile: 'typedoc-sidebar.js',
         categoryLabel: 'API',
         indexLabel: undefined,
         readmeLabel: 'Readme',
         position: null,
     },
-    plugin: ['none'],
-    watch: false,
     hideInPageTOC: true,
     hideBreadcrumbs: true,
     hidePageTitle: true,
     entryDocument: 'index.md',
+    plugin: ['none'],
+    watch: false,
+    indexSlug: undefined,
 };
 const getPluginOptions = (opts) => {
     const options = {
@@ -52,7 +32,3 @@ const getPluginOptions = (opts) => {
     return options;
 };
 exports.getPluginOptions = getPluginOptions;
-const getOutputDirectory = (siteDir, options) => {
-    return path.resolve(siteDir, options.docsRoot, path.relative(process.cwd(), options.out));
-};
-exports.getOutputDirectory = getOutputDirectory;

package/dist/plugin.js

@@ -24,30 +24,29 @@ const typedoc_1 = require("typedoc");
 const typedoc_plugin_markdown_1 = require("typedoc-plugin-markdown");
 const options_1 = require("./options");
 const render_1 = require("./render");
-const sidebar_1 = require("./sidebar");
 const apps = [];
 async function pluginDocusaurus(context, opts) {
     if (opts.id && !apps.includes(opts.id)) {
         apps.push(opts.id);
         const { siteDir } = context;
+        const options = (0, options_1.getPluginOptions)(opts);
+        const outputDir = path.resolve(siteDir, options.docsRoot, options.out);
+        (0, render_1.removeDir)(outputDir);
         const app = new typedoc_1.Application();
         app.options.setValue('theme', path.resolve(__dirname));
         (0, typedoc_plugin_markdown_1.load)(app);
-        const options = (0, render_1.bootstrap)(app, opts);
-        if (options.sidebar.sidebarFile) {
-            (0, sidebar_1.writeSidebar)(siteDir, options);
-        }
+        (0, render_1.bootstrap)(app, options);
         const project = app.convert();
         if (!project) {
             return;
         }
         if (options.watch) {
             app.convertAndWatch(async (project) => {
-                await app.generateDocs(project, (0, options_1.getOutputDirectory)(siteDir, options));
+                await app.generateDocs(project, outputDir);
             });
         }
         else {
-            await app.generateDocs(project, (0, options_1.getOutputDirectory)(siteDir, options));
+            await app.generateDocs(project, outputDir);
         }
     }
     return {

package/dist/render.d.ts

@@ -1,3 +1,4 @@
 import { Application } from 'typedoc';
 import { PluginOptions } from './types';
-export declare const bootstrap: (app: Application, opts: Partial<PluginOptions>) => PluginOptions;
+export declare const bootstrap: (app: Application, options: PluginOptions) => void;
+export declare function removeDir(path: string): void;

package/dist/render.js

@@ -1,15 +1,46 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.bootstrap = void 0;
+exports.removeDir = exports.bootstrap = void 0;
+const fs = __importStar(require("fs"));
 const typedoc_1 = require("typedoc");
-const options_1 = require("./options");
-const bootstrap = (app, opts) => {
+const bootstrap = (app, options) => {
     addTypedocReaders(app);
     addTypedocDeclarations(app);
-    app.bootstrap({ ...(0, options_1.getPluginOptions)(opts) });
-    return app.options.getRawValues();
+    app.renderer.render = render;
+    app.bootstrap(options);
 };
 exports.bootstrap = bootstrap;
+async function render(project, outputDirectory) {
+    var _a;
+    const output = new typedoc_1.RendererEvent(typedoc_1.RendererEvent.BEGIN, outputDirectory, project);
+    output.urls = this.theme.getUrls(project);
+    this.trigger(output);
+    if (!output.isDefaultPrevented) {
+        (_a = output === null || output === void 0 ? void 0 : output.urls) === null || _a === void 0 ? void 0 : _a.forEach((mapping) => {
+            this.renderDocument(output.createPageEvent(mapping));
+        });
+        this.trigger(typedoc_1.RendererEvent.END, output);
+    }
+}
 const addTypedocReaders = (app) => {
     app.options.addReader(new typedoc_1.TypeDocReader());
     app.options.addReader(new typedoc_1.TSConfigReader());
@@ -30,8 +61,31 @@ const addTypedocDeclarations = (app) => {
     app.options.addDeclaration({
         name: 'readmeTitle',
     });
+    app.options.addDeclaration({
+        name: 'indexSlug',
+    });
     app.options.addDeclaration({
         name: 'sidebar',
         type: typedoc_1.ParameterType.Mixed,
     });
 };
+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/theme.d.ts

@@ -4,6 +4,7 @@ import { SidebarOptions } from './types';
 export declare class DocusaurusTheme extends MarkdownTheme {
     sidebar: SidebarOptions;
     readmeTitle: string;
+    indexSlug: string;
     constructor(renderer: Renderer);
     getRelativeUrl(url: string): string;
     onPageEnd(page: PageEvent<DeclarationReflection>): void;
@@ -13,6 +14,7 @@ export declare class DocusaurusTheme extends MarkdownTheme {
     getSidebarPosition(page: PageEvent<DeclarationReflection>): "0.5" | "0" | null;
     getId(page: PageEvent): string;
     getTitle(page: PageEvent): any;
+    getSlug(): string;
     get mappings(): {
         kind: ReflectionKind[];
         isLeaf: boolean;

package/dist/theme.js

@@ -83,10 +83,7 @@ class DocusaurusTheme extends theme_1.MarkdownTheme {
             title: pageTitle,
         };
         if (page.url === this.entryDocument) {
-            items = {
-                ...items,
-                slug: '/' + path.relative(process.cwd(), this.out).replace(/\\/g, '/') + '/',
-            };
+            items = { ...items, slug: this.getSlug() };
         }
         if (sidebarLabel && sidebarLabel !== pageTitle) {
             items = { ...items, sidebar_label: sidebarLabel };
@@ -137,6 +134,15 @@ class DocusaurusTheme extends theme_1.MarkdownTheme {
         }
         return (0, front_matter_1.getPageTitle)(page);
     }
+    getSlug() {
+        if (this.indexSlug) {
+            return this.indexSlug;
+        }
+        if (this.out === process.cwd()) {
+            return '/';
+        }
+        return `/${path.relative(process.cwd(), this.out).replace(/\\/g, '/')}/`;
+    }
     get mappings() {
         return super.mappings.map((mapping) => {
             if (mapping.kind.includes(typedoc_1.ReflectionKind.Namespace)) {
@@ -158,6 +164,9 @@ __decorate([
 __decorate([
     (0, typedoc_1.BindOption)('readmeTitle')
 ], DocusaurusTheme.prototype, "readmeTitle", void 0);
+__decorate([
+    (0, typedoc_1.BindOption)('indexSlug')
+], DocusaurusTheme.prototype, "indexSlug", void 0);
 exports.DocusaurusTheme = DocusaurusTheme;
 const writeCategoryYaml = (categoryPath, label, position) => {
     const yaml = [`label: "${label}"`];

package/dist/types.d.ts

@@ -14,6 +14,7 @@ export interface PluginOptions {
     hideBreadcrumbs: boolean;
     hidePageTitle: boolean;
     entryDocument: string;
+    indexSlug?: string;
 }
 export interface FrontMatter {
     id: string;
@@ -26,7 +27,6 @@ export interface FrontMatter {
 }
 export interface SidebarOptions {
     fullNames?: boolean;
-    sidebarFile: string;
     categoryLabel: string;
     indexLabel?: string;
     readmeLabel?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-typedoc",
-  "version": "0.16.1",
+  "version": "0.16.5",
   "description": "A Docusaurus v2 plugin to build API documentation with TypeDoc.",
   "main": "dist/index.js",
   "files": [
@@ -28,8 +28,8 @@
     "build": "rm -rf ./dist && tsc",
     "build-and-test": "yarn run build && yarn run test",
     "test:init": "rm -rf test/site && npx @docusaurus/init@latest init test/site classic",
-    "test:demo:start": "yarn run build && cd test/site && yarn run clear && yarn run start",
-    "test:demo:build": "yarn run build && cd test/site && yarn run clear && yarn run build && yarn run serve",
+    "test:demo:start": "yarn run build && cd test/site && yarn run start",
+    "test:demo:build": "yarn run build && cd test/site && yarn run build && yarn run serve",
     "test": "jest --colors"
   },
   "author": "Thomas Grey",
@@ -42,5 +42,5 @@
     "typescript",
     "api"
   ],
-  "gitHead": "54ab24b8b655e3c401469ea95c841b5a969bb40a"
+  "gitHead": "eb289daac347deea984351f04ec7d5f82896d281"
 }

package/dist/sidebar.d.ts

@@ -1,2 +0,0 @@
-import { PluginOptions } from './types';
-export declare const writeSidebar: (siteDir: string, options: PluginOptions) => void;

package/dist/sidebar.js

@@ -1,32 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeSidebar = void 0;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const writeSidebar = (siteDir, options) => {
-    const sidebarPath = path.resolve(siteDir, options.sidebar.sidebarFile);
-    if (!fs.existsSync(path.dirname(sidebarPath))) {
-        fs.mkdirSync(path.dirname(sidebarPath));
-    }
-    fs.writeFileSync(sidebarPath, `module.exports=[{type:'autogenerated',dirName:'${path.relative(process.cwd(), options.out)}'}];`);
-};
-exports.writeSidebar = writeSidebar;