docusaurus-plugin-typedoc 0.16.8 → 0.17.2

package/README.md

@@ -32,7 +32,7 @@ module.exports = {
       // Plugin / TypeDoc options
       {
         entryPoints: ['../src/index.ts'],
-        tsconfig: '../tsconfig.json'
+        tsconfig: '../tsconfig.json',
       },
     ],
   ],
@@ -63,7 +63,6 @@ Once built the docs will be available at `/docs/api` (or equivalent out director
 ├──tsconfig.json
 ```
 
-
 ## Options
 
 ### TypeDoc options
@@ -80,7 +79,7 @@ tsconfig: '../tsconfig.json'
 Additional TypeDoc plugins will need to be explicitly set:
 
 ```js
-plugin:['typedoc-plugin-xyz']
+plugin: ['typedoc-plugin-xyz'];
 ```
 
 #### Other config options
@@ -96,18 +95,19 @@ 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 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.                 |
+| Name                    | Default | Description                                                                                                                                                                                                  |
+| :---------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `out`                   | `"api"` | Output dir relative to docs dir (use `.` for no subdir).                                                                                                                                                     |
+| `includeExtension`      | `true`  | Determines whether to preserve the `.md` extension in relative links. `true` is recommended as per [Docusaurus documentation](https://docusaurus.io/docs/docs-markdown-features#referencing-other-documents) |
+| `frontmatter`           | `null`  | Additional frontmatter options object. See [Frontmatter](#frontmatter).                                                                                                                                      |
+| `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
 
 ```js
 module.exports = {
-
   plugins: [
     [
       'docusaurus-plugin-typedoc',
@@ -115,14 +115,14 @@ module.exports = {
         // TypeDoc options
         entryPoints: ['../src/index.ts'],
         tsconfig: '../tsconfig.json',
-        plugin:['typedoc-plugin-xyz'],
+        plugin: ['typedoc-plugin-xyz'],
 
         // Plugin options
         out: 'api-xyz',
         sidebar: {
           categoryLabel: 'API XYZ',
           position: 0,
-          fullNames: true
+          fullNames: true,
         },
       },
     ],
@@ -130,7 +130,6 @@ module.exports = {
 };
 ```
 
-
 ## Recipes
 
 ### Sidebar and Navbar
@@ -139,7 +138,7 @@ module.exports = {
 
 `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 = {
@@ -152,7 +151,7 @@ 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)
 
@@ -160,7 +159,7 @@ module.exports = {
 module.exports = {
   sidebar: {
     'Category 1': ['doc1', 'doc2', 'doc3'],
-    'API': [
+    API: [
       {
         type: 'autogenerated',
         dirName: 'api', // 'api' is the 'out' directory
@@ -193,29 +192,52 @@ 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.
 
+### Frontmatter
+
+By default the plugin will configure minimal required [Frontmatter](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter) configuration.
+Additionally required global Frontmatter options can be passed in using the `frontmatter` options object
+
+`docusaurus.config.js`:
+
+```js
+plugins: [
+    [
+      'docusaurus-plugin-typedoc',
+      {
+      // .... other plugin option
+      frontmatter: {
+        pagination_prev: null,
+        pagination_next: null
+      }
+    ]
+]
+```
 
 ### Multi instance
 
 It is possible to build multi TypeDoc instances by passing in multiple configs with unique ids:
 
 `docusaurus.config.js`
+
 ```js
 module.exports = {
   plugins: [
     [
       'docusaurus-plugin-typedoc',
       {
-        id:'api-1',
+        id: 'api-1',
         entryPoints: ['../api-1/src/index.ts'],
         tsconfig: '../api-1/tsconfig.json',
+        out: 'api-1',
       },
     ],
     [
       'docusaurus-plugin-typedoc',
       {
-        id:'api-2',
+        id: 'api-2',
         entryPoints: ['../api-2/src/index.ts'],
         tsconfig: '../api-2/tsconfig.json',
+        out: 'api-2',
       },
     ],
   ],
@@ -265,7 +287,7 @@ module.exports = {
         entryPoints: ['../packages/package-a', '../packages/package-b'],
         entryPointStrategy: 'packages',
         sidebar: {
-          fullNames: true
+          fullNames: true,
         },
       },
     ],

package/dist/options.js

@@ -5,6 +5,7 @@ const DEFAULT_PLUGIN_OPTIONS = {
     id: 'default',
     docsRoot: 'docs',
     out: 'api',
+    cleanOutputDir: true,
     sidebar: {
         fullNames: false,
         categoryLabel: 'API',
@@ -18,8 +19,10 @@ const DEFAULT_PLUGIN_OPTIONS = {
     entryDocument: 'index.md',
     plugin: ['none'],
     watch: false,
+    includeExtension: true,
     indexSlug: undefined,
     theme: 'docusaurus',
+    frontmatter: undefined,
 };
 const getPluginOptions = (opts) => {
     const options = {

package/dist/plugin.d.ts

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

package/dist/plugin.js

@@ -1,7 +1,11 @@
 "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]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
@@ -35,7 +39,9 @@ function pluginDocusaurus(context, opts) {
                 const { siteDir } = context;
                 const options = (0, options_1.getPluginOptions)(opts);
                 const outputDir = path.resolve(siteDir, options.docsRoot, options.out);
-                (0, render_1.removeDir)(outputDir);
+                if (opts.cleanOutputDir) {
+                    (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);

package/dist/render.js

@@ -1,7 +1,11 @@
 "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]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
@@ -68,10 +72,17 @@ const addTypedocDeclarations = (app) => {
     app.options.addDeclaration({
         name: 'indexSlug',
     });
+    app.options.addDeclaration({
+        name: 'includeExtension',
+    });
     app.options.addDeclaration({
         name: 'sidebar',
         type: typedoc_1.ParameterType.Mixed,
     });
+    app.options.addDeclaration({
+        name: 'frontmatter',
+        type: typedoc_1.ParameterType.Mixed,
+    });
 };
 function removeDir(path) {
     if (fs.existsSync(path)) {

package/dist/theme.d.ts

@@ -1,15 +1,17 @@
 import { DeclarationReflection, PageEvent, ReflectionKind, Renderer, RendererEvent } from 'typedoc';
 import { MarkdownTheme } from 'typedoc-plugin-markdown/dist/theme';
-import { SidebarOptions } from './types';
+import { FrontMatter, SidebarOptions } from './types';
 export declare class DocusaurusTheme extends MarkdownTheme {
     sidebar: SidebarOptions;
     readmeTitle: string;
     indexSlug: string;
+    includeExtension: string;
+    frontmatter: FrontMatter;
     constructor(renderer: Renderer);
     getRelativeUrl(url: string): string;
     onPageEnd(page: PageEvent<DeclarationReflection>): void;
     onRendererEnd(renderer: RendererEvent): void;
-    getYamlItems(page: PageEvent<DeclarationReflection>): any;
+    getYamlItems(page: PageEvent<DeclarationReflection>): FrontMatter;
     getSidebarLabel(page: PageEvent<DeclarationReflection>): string | undefined;
     getSidebarPosition(page: PageEvent<DeclarationReflection>): "0.5" | "0" | null;
     getId(page: PageEvent): string;

package/dist/theme.js

@@ -1,7 +1,11 @@
 "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]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
@@ -52,9 +56,10 @@ class DocusaurusTheme extends theme_1.MarkdownTheme {
         });
     }
     getRelativeUrl(url) {
-        const relativeUrl = super.getRelativeUrl(url);
+        const re = new RegExp(this.includeExtension === 'true' ? '' : '.md', 'g');
+        const relativeUrl = super.getRelativeUrl(url).replace(re, '');
         if (path.basename(relativeUrl).startsWith('index')) {
-            return relativeUrl.replace('index', '');
+            return relativeUrl.replace('index', '').replace('.md', '');
         }
         return relativeUrl;
     }
@@ -94,9 +99,12 @@ class DocusaurusTheme extends theme_1.MarkdownTheme {
         if (page.url === page.project.url && this.entryPoints.length > 1) {
             items = { ...items, hide_table_of_contents: true };
         }
+        items = { ...items, custom_edit_url: null };
+        if (this.frontmatter) {
+            items = { ...items, ...this.frontmatter };
+        }
         return {
             ...items,
-            custom_edit_url: null,
         };
     }
     getSidebarLabel(page) {
@@ -167,6 +175,12 @@ __decorate([
 __decorate([
     (0, typedoc_1.BindOption)('indexSlug')
 ], DocusaurusTheme.prototype, "indexSlug", void 0);
+__decorate([
+    (0, typedoc_1.BindOption)('includeExtension')
+], DocusaurusTheme.prototype, "includeExtension", void 0);
+__decorate([
+    (0, typedoc_1.BindOption)('frontmatter')
+], DocusaurusTheme.prototype, "frontmatter", void 0);
 exports.DocusaurusTheme = DocusaurusTheme;
 const writeCategoryYaml = (categoryPath, label, position) => {
     const yaml = [`label: "${label}"`];

package/dist/types.d.ts

@@ -8,24 +8,19 @@ export interface PluginOptions {
     plugin: string[];
     readme?: string;
     disableOutputCheck?: boolean;
+    cleanOutputDir?: boolean;
     entryPoints?: string[];
     watch: boolean;
     hideInPageTOC: boolean;
     hideBreadcrumbs: boolean;
     hidePageTitle: boolean;
     entryDocument: string;
+    includeExtension?: boolean;
     indexSlug?: string;
     theme?: string;
+    frontmatter: FrontMatter;
 }
-export interface FrontMatter {
-    id: string;
-    title: string;
-    slug?: string;
-    sidebar_label?: string;
-    sidebar_position?: number;
-    hide_title?: boolean;
-    hide_table_of_contents?: boolean;
-}
+export declare type FrontMatter = Record<string, string | boolean | number | null> | undefined;
 export interface SidebarOptions {
     fullNames?: boolean;
     categoryLabel: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-typedoc",
-  "version": "0.16.8",
+  "version": "0.17.2",
   "description": "A Docusaurus v2 plugin to build API documentation with TypeDoc.",
   "main": "dist/index.js",
   "files": [
@@ -19,15 +19,12 @@
     "typedoc": ">=0.22.0",
     "typedoc-plugin-markdown": ">=3.11.10"
   },
-  "devDependencies": {
-    "@docusaurus/types": "^2.0.0-beta.0"
-  },
   "scripts": {
     "lint": "eslint ./src --ext .ts",
     "prepublishOnly": "yarn run lint && yarn run build && yarn run test",
     "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:init": "rm -rf test/site && npx npx create-docusaurus@latest test/site classic",
     "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"
@@ -42,5 +39,5 @@
     "typescript",
     "api"
   ],
-  "gitHead": "eb688bb8ef85b24fc873f80d6182804fcc2d2dfc"
+  "gitHead": "34c68d8adcb9ba75af53f35dcf830caec4020be7"
 }