docusaurus-plugin-typedoc 0.16.6 → 0.17.0

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,20 @@ 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.                                                                                                                                                                     |
+| `sidebar.position`      | `auto`  | The position of the sidebar in the tree.                                                                                                                                                                     |
 
 ### An example configuration
 
 ```js
 module.exports = {
-
   plugins: [
     [
       'docusaurus-plugin-typedoc',
@@ -115,14 +116,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 +131,6 @@ module.exports = {
 };
 ```
 
-
 ## Recipes
 
 ### Sidebar and Navbar
@@ -139,7 +139,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 +152,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 +160,7 @@ module.exports = {
 module.exports = {
   sidebar: {
     'Category 1': ['doc1', 'doc2', 'doc3'],
-    'API': [
+    API: [
       {
         type: 'autogenerated',
         dirName: 'api', // 'api' is the 'out' directory
@@ -193,19 +193,40 @@ 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',
       },
@@ -213,7 +234,7 @@ module.exports = {
     [
       'docusaurus-plugin-typedoc',
       {
-        id:'api-2',
+        id: 'api-2',
         entryPoints: ['../api-2/src/index.ts'],
         tsconfig: '../api-2/tsconfig.json',
       },
@@ -265,7 +286,7 @@ module.exports = {
         entryPoints: ['../packages/package-a', '../packages/package-b'],
         entryPointStrategy: 'packages',
         sidebar: {
-          fullNames: true
+          fullNames: true,
         },
       },
     ],

package/dist/options.js

@@ -18,7 +18,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.js

@@ -24,6 +24,7 @@ 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 = [];
 function pluginDocusaurus(context, opts) {
     return {
@@ -36,7 +37,7 @@ function pluginDocusaurus(context, 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));
+                app.renderer.defineTheme('docusaurus', theme_1.DocusaurusTheme);
                 (0, typedoc_plugin_markdown_1.load)(app);
                 (0, render_1.bootstrap)(app, options);
                 const project = app.convert();

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());
@@ -64,10 +68,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

@@ -52,9 +52,10 @@ class DocusaurusTheme extends theme_1.MarkdownTheme {
         });
     }
     getRelativeUrl(url) {
-        const relativeUrl = super.getRelativeUrl(url).replace(/.md/g, '');
+        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 +95,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 +171,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

@@ -14,17 +14,12 @@ export interface PluginOptions {
     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.6",
+  "version": "0.17.0",
   "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"
@@ -30,7 +30,7 @@
     "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 start",
     "test:demo:build": "yarn run build && cd test/site && yarn run build && yarn run serve",
-    "test": "jest --colors"
+    "test": "jest --colors --updateSnapshot"
   },
   "author": "Thomas Grey",
   "license": "MIT",
@@ -42,5 +42,5 @@
     "typescript",
     "api"
   ],
-  "gitHead": "eece3f13ce3b48ac51c119b432869983fc45cc6d"
+  "gitHead": "39b0da170611c2e27c821ef2f1869ff2e4bb0125"
 }