docusaurus-plugin-typedoc 0.16.4 → 0.16.8

package/README.md

@@ -11,24 +11,12 @@ Generates static TypeDoc pages in Markdown with frontmatter as part of the Docus
 
 ## Installation
 
-1. Install Docusaurus in the root of your project. See https://v2.docusaurus.io/docs/installation.
-
-2. Install the plugin dependencies in the same location as the Docusaurus website directory.
+> 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
-cd docs-website
 npm install typedoc typedoc-plugin-markdown docusaurus-plugin-typedoc --save-dev
 ```
 
-```
-├──docs-website (docusaurus location)
-   ├── package.json
-├──package.json
-├──src (typescript source files)
-├──tsconfig.json
-
-```
-
 ## Usage
 
 ### Config
@@ -58,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
 
 ```
-docs-website
-├── 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
 ```
 
 
@@ -103,12 +96,12 @@ TypeDoc options can also be declared:
 
 Options specific to the plugin should also be declared in the same object.
 
-| 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.     |
+| 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
 
@@ -137,13 +130,16 @@ module.exports = {
 };
 ```
 
-## Sidebar and Navbar
 
-### Sidebar
+## 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 = {
@@ -156,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 = {
@@ -176,7 +172,7 @@ module.exports = {
 
 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`:
 
@@ -197,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
 

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);
@@ -41,6 +44,7 @@ async function render(project, outputDirectory) {
         this.trigger(typedoc_1.RendererEvent.END, output);
     }
 }
+exports.render = render;
 const addTypedocReaders = (app) => {
     app.options.addReader(new typedoc_1.TypeDocReader());
     app.options.addReader(new typedoc_1.TSConfigReader());
@@ -61,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

@@ -52,7 +52,7 @@ class DocusaurusTheme extends theme_1.MarkdownTheme {
         });
     }
     getRelativeUrl(url) {
-        const relativeUrl = super.getRelativeUrl(url).replace(/.md/g, '');
+        const relativeUrl = super.getRelativeUrl(url);
         if (path.basename(relativeUrl).startsWith('index')) {
             return relativeUrl.replace('index', '');
         }
@@ -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.4",
+  "version": "0.16.8",
   "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": "07d11744f1312dda8f1017b5ab54456f3521eb75"
+  "gitHead": "eb688bb8ef85b24fc873f80d6182804fcc2d2dfc"
 }