docusaurus-plugin-typedoc 0.16.2 → 0.16.6

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,16 +46,21 @@ 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 `/docs/api` (or equivalent out directory).
+
+### Directory structure
 
 ```
-website/ (docusaururs website root)
-├── build/ (static site dir)
-├── docs/
-│   ├── api/ (compiled typedoc markdown)
-├── docusaurus.config.js
-├── package.json
-├── sidebars.js
+├── 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
 ```
 
 
@@ -88,16 +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.
+
+| 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
 
@@ -126,13 +130,16 @@ module.exports = {
 };
 ```
 
+
+## 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):
+1) Generate the entire sidebar from file structure of your docs folder (default behaviour):
 
 ```js
 module.exports = {
@@ -145,9 +152,9 @@ module.exports = {
 };
 ```
 
-2 ) Alternatively, if you wish to manually control other parts of your sidebar you can use a slice for the TypeDoc sidebar.
+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)
+> note: `sidebar.categoryLabel` and `sidebar.position` options are ignored with this implementation)
 
 ```js
 module.exports = {
@@ -186,7 +193,6 @@ 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.
 
-## Additional config
 
 ### Multi instance
 
@@ -246,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,26 +1,6 @@
 "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',
@@ -32,12 +12,13 @@ const DEFAULT_PLUGIN_OPTIONS = {
         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 = {
@@ -51,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.d.ts

@@ -1,5 +1,6 @@
 import { LoadContext } from '@docusaurus/types';
 import { PluginOptions } from './types';
-export default function pluginDocusaurus(context: LoadContext, opts: Partial<PluginOptions>): Promise<{
+export default function pluginDocusaurus(context: LoadContext, opts: Partial<PluginOptions>): {
     name: string;
-} | undefined>;
+    loadContent(): Promise<void>;
+};

package/dist/plugin.js

@@ -25,29 +25,34 @@ const typedoc_plugin_markdown_1 = require("typedoc-plugin-markdown");
 const options_1 = require("./options");
 const render_1 = require("./render");
 const apps = [];
-async function pluginDocusaurus(context, opts) {
-    if (opts.id && !apps.includes(opts.id)) {
-        apps.push(opts.id);
-        const { siteDir } = context;
-        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);
-        const project = app.convert();
-        if (!project) {
-            return;
-        }
-        if (options.watch) {
-            app.convertAndWatch(async (project) => {
-                await app.generateDocs(project, (0, options_1.getOutputDirectory)(siteDir, options));
-            });
-        }
-        else {
-            await app.generateDocs(project, (0, options_1.getOutputDirectory)(siteDir, options));
-        }
-    }
+function pluginDocusaurus(context, opts) {
     return {
         name: 'docusaurus-plugin-typedoc',
+        async loadContent() {
+            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);
+                (0, render_1.bootstrap)(app, options);
+                const project = app.convert();
+                if (!project) {
+                    return;
+                }
+                if (options.watch) {
+                    app.convertAndWatch(async (project) => {
+                        await app.generateDocs(project, outputDir);
+                    });
+                }
+                else {
+                    await app.generateDocs(project, outputDir);
+                }
+            }
+        },
     };
 }
 exports.default = pluginDocusaurus;

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,22 +1,36 @@
 "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.renderer.render = render;
-    app.bootstrap({ ...(0, options_1.getPluginOptions)(opts) });
-    return app.options.getRawValues();
+    app.bootstrap(options);
 };
 exports.bootstrap = bootstrap;
 async function render(project, outputDirectory) {
     var _a;
-    if (!this.prepareTheme() ||
-        !(await this.prepareOutputDirectory(outputDirectory))) {
-        return;
-    }
     const output = new typedoc_1.RendererEvent(typedoc_1.RendererEvent.BEGIN, outputDirectory, project);
     output.urls = this.theme.getUrls(project);
     this.trigger(output);
@@ -26,7 +40,6 @@ async function render(project, outputDirectory) {
         });
         this.trigger(typedoc_1.RendererEvent.END, output);
     }
-    this.theme = void 0;
 }
 const addTypedocReaders = (app) => {
     app.options.addReader(new typedoc_1.TypeDocReader());
@@ -48,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-typedoc",
-  "version": "0.16.2",
+  "version": "0.16.6",
   "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": "rm -rf test/site/docs/api yarn run build && cd test/site && yarn run clear && yarn run start",
-    "test:demo:build": "rm -rf test/site/docs/api && 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": "0a55775a328b98d92b3afa499741549c5f333d47"
+  "gitHead": "eece3f13ce3b48ac51c119b432869983fc45cc6d"
 }