docusaurus-plugin-typedoc 0.16.3 → 0.16.7

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.js

@@ -18,6 +18,8 @@ const DEFAULT_PLUGIN_OPTIONS = {
     entryDocument: 'index.md',
     plugin: ['none'],
     watch: false,
+    indexSlug: undefined,
+    theme: 'docusaurus',
 };
 const getPluginOptions = (opts) => {
     const options = {

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

@@ -24,33 +24,36 @@ 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 theme_1 = require("./theme");
 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);
-        (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);
-        }
-    }
+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.renderer.defineTheme('docusaurus', theme_1.DocusaurusTheme);
+                (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,4 +1,5 @@
-import { Application } from 'typedoc';
+import { Application, ProjectReflection } from 'typedoc';
 import { PluginOptions } from './types';
 export declare const bootstrap: (app: Application, options: PluginOptions) => void;
+export declare function render(project: ProjectReflection, outputDirectory: string): Promise<void>;
 export declare function removeDir(path: string): void;

package/dist/render.js

@@ -19,7 +19,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.removeDir = exports.bootstrap = void 0;
+exports.removeDir = exports.render = exports.bootstrap = void 0;
 const fs = __importStar(require("fs"));
 const typedoc_1 = require("typedoc");
 const bootstrap = (app, options) => {
@@ -31,6 +31,9 @@ const bootstrap = (app, options) => {
 exports.bootstrap = bootstrap;
 async function render(project, outputDirectory) {
     var _a;
+    if (!this.prepareTheme()) {
+        return;
+    }
     const output = new typedoc_1.RendererEvent(typedoc_1.RendererEvent.BEGIN, outputDirectory, project);
     output.urls = this.theme.getUrls(project);
     this.trigger(output);
@@ -40,8 +43,8 @@ async function render(project, outputDirectory) {
         });
         this.trigger(typedoc_1.RendererEvent.END, output);
     }
-    this.theme = void 0;
 }
+exports.render = render;
 const addTypedocReaders = (app) => {
     app.options.addReader(new typedoc_1.TypeDocReader());
     app.options.addReader(new typedoc_1.TSConfigReader());
@@ -62,6 +65,9 @@ const addTypedocDeclarations = (app) => {
     app.options.addDeclaration({
         name: 'readmeTitle',
     });
+    app.options.addDeclaration({
+        name: 'indexSlug',
+    });
     app.options.addDeclaration({
         name: 'sidebar',
         type: typedoc_1.ParameterType.Mixed,

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,8 @@ export interface PluginOptions {
     hideBreadcrumbs: boolean;
     hidePageTitle: boolean;
     entryDocument: string;
+    indexSlug?: string;
+    theme?: string;
 }
 export interface FrontMatter {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-typedoc",
-  "version": "0.16.3",
+  "version": "0.16.7",
   "description": "A Docusaurus v2 plugin to build API documentation with TypeDoc.",
   "main": "dist/index.js",
   "files": [
@@ -16,8 +16,8 @@
   },
   "homepage": "https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/docusaurus-plugin-typedoc",
   "peerDependencies": {
-    "typedoc": ">=0.21.0",
-    "typedoc-plugin-markdown": ">=3.10.0"
+    "typedoc": ">=0.22.0",
+    "typedoc-plugin-markdown": ">=3.11.10"
   },
   "devDependencies": {
     "@docusaurus/types": "^2.0.0-beta.0"
@@ -42,5 +42,5 @@
     "typescript",
     "api"
   ],
-  "gitHead": "9cc0d903c124638d70a0d5e94108baeae8196d41"
+  "gitHead": "7a9b045eaacfdafd14c3427379d410c45f6b990b"
 }