fix: remove manual sidebar generation and fix pre-render docs order (#…

…251)
typedoc2md · Sep 18, 2021 · eb21cb4 · eb21cb4
1 parent 54ab24b
commit eb21cb4
Show file tree

Hide file tree

Showing 9 changed files with 89 additions and 76 deletions.
diff --git a/packages/docusaurus-plugin-typedoc/README.md b/packages/docusaurus-plugin-typedoc/README.md
@@ -61,49 +61,6 @@ website/ (docusaururs website root)
 ├── sidebars.js
 ```
 
-### Sidebar
-
-`sidebars.js` can be configured in following ways:
-
-1 ) Generate the entire sidebar from file structure of your docs folder (default behaviour):
-
-```js
-module.exports = {
-  someSidebar: [
-    {
-      type: 'autogenerated',
-      dirName: '.', // '.' means the docs folder
-    },
-  ],
-};
-```
-
-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)
-
-
-```js
-module.exports = {
-  someSidebar: {
-    'Category 1': ['doc1', 'doc2', 'doc3'],
-
-    // use seperate generated file
-    'API': require('./typedoc-sidebar.js'),
-
-    // or write inline
-    'API': [
-      {
-        type: 'autogenerated',
-        dirName: 'api', // 'api' is the 'out' directory
-      },
-    ],
-  },
-};
-```
-
-> To maintain backward compatibility with previous versions a `./typedoc-sidebar.js` is created by default. Pass `sidebar.sidebarFile:null` to prevent this.
-
-Please see https://docusaurus.io/docs/sidebar for sidebar documentation.
 
 ## Options
 
@@ -142,8 +99,6 @@ Note: Options declared in this manner will take priority and overwrite options d
 | `sidebar.fullNames`     | `false` | Display full names with module path.         |
 | `sidebar.position`      | `null`  | The position of the sidebar in the tree.     |
 
-If the manual sidebar is not required pass `sidebar.sidebarFile: null` to skip sidebar generation.
-
 ### An example configuration
 
 ```js
@@ -171,6 +126,65 @@ module.exports = {
 };
 ```
 
+### 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):
+
+```js
+module.exports = {
+  sidebar: [
+    {
+      type: 'autogenerated',
+      dirName: '.', // '.' means the docs folder
+    },
+  ],
+};
+```
+
+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)
+
+```js
+module.exports = {
+  sidebar: {
+    'Category 1': ['doc1', 'doc2', 'doc3'],
+    'API': [
+      {
+        type: 'autogenerated',
+        dirName: 'api', // 'api' is the 'out' directory
+      },
+    ],
+  },
+};
+```
+
+Please see https://docusaurus.io/docs/sidebar for sidebar documentation.
+
+#### Navbar
+
+A navbar item can be configured in `themeConfig` options in `docusaurus.config.js`:
+
+```js
+ themeConfig: {
+    navbar: {
+      items: [
+        {
+        to: 'docs/api/',  // 'api' is the 'out' directory
+        activeBasePath: 'docs',
+        label: 'API',
+        position: 'left',
+      },
+    ],
+  },
+},
+```
+
+Please see https://docusaurus.io/docs/api/themes/configuration#navbar-items for navbar documentation.
 
 ## Additional config
 

diff --git a/packages/docusaurus-plugin-typedoc/package.json b/packages/docusaurus-plugin-typedoc/package.json
@@ -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": "yarn run build && cd test/site && yarn run clear && yarn run start",
-    "test:demo:build": "yarn run build && cd test/site && yarn run clear && yarn run build && yarn run serve",
+    "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": "jest --colors"
   },
   "author": "Thomas Grey",

diff --git a/packages/docusaurus-plugin-typedoc/src/options.ts b/packages/docusaurus-plugin-typedoc/src/options.ts
@@ -8,7 +8,6 @@ const DEFAULT_PLUGIN_OPTIONS: PluginOptions = {
   out: 'api',
   sidebar: {
     fullNames: false,
-    sidebarFile: 'typedoc-sidebar.js',
     categoryLabel: 'API',
     indexLabel: undefined,
     readmeLabel: 'Readme',

diff --git a/packages/docusaurus-plugin-typedoc/src/plugin.ts b/packages/docusaurus-plugin-typedoc/src/plugin.ts
@@ -6,7 +6,6 @@ import { load } from 'typedoc-plugin-markdown';
 
 import { getOutputDirectory } from './options';
 import { bootstrap } from './render';
-import { writeSidebar } from './sidebar';
 import { PluginOptions } from './types';
 
 // store list of plugin ids when running multiple instances
@@ -29,11 +28,6 @@ export default async function pluginDocusaurus(
 
     const options = bootstrap(app, opts);
 
-    // Do not break legacy manual sidebar generation implementations
-    if (options.sidebar.sidebarFile) {
-      writeSidebar(siteDir, options);
-    }
-
     const project = app.convert();
 
     // if project is undefined typedoc has a problem - error logging will be supplied by typedoc.

diff --git a/packages/docusaurus-plugin-typedoc/src/render.ts b/packages/docusaurus-plugin-typedoc/src/render.ts
@@ -2,9 +2,12 @@ import {
   Application,
   MixedDeclarationOption,
   ParameterType,
+  ProjectReflection,
+  RendererEvent,
   StringDeclarationOption,
   TSConfigReader,
   TypeDocReader,
+  UrlMapping,
 } from 'typedoc';
 
 import { getPluginOptions } from './options';
@@ -14,10 +17,35 @@ import { PluginOptions } from './types';
 export const bootstrap = (app: Application, opts: Partial<PluginOptions>) => {
   addTypedocReaders(app);
   addTypedocDeclarations(app);
+  app.renderer.render = render;
   app.bootstrap({ ...getPluginOptions(opts) });
   return app.options.getRawValues() as PluginOptions;
 };
 
+async function render(project: ProjectReflection, outputDirectory: string) {
+  if (
+    !this.prepareTheme() ||
+    !(await this.prepareOutputDirectory(outputDirectory))
+  ) {
+    return;
+  }
+  const output = new RendererEvent(
+    RendererEvent.BEGIN,
+    outputDirectory,
+    project,
+  );
+  output.urls = this.theme!.getUrls(project);
+  this.trigger(output);
+  if (!output.isDefaultPrevented) {
+    output?.urls?.forEach((mapping: UrlMapping) => {
+      this.renderDocument(output.createPageEvent(mapping));
+    });
+
+    this.trigger(RendererEvent.END, output);
+  }
+  this.theme = void 0;
+}
+
 const addTypedocReaders = (app: Application) => {
   app.options.addReader(new TypeDocReader());
   app.options.addReader(new TSConfigReader());

diff --git a/packages/docusaurus-plugin-typedoc/src/sidebar.ts b/packages/docusaurus-plugin-typedoc/src/sidebar.ts
diff --git a/packages/docusaurus-plugin-typedoc/src/types.ts b/packages/docusaurus-plugin-typedoc/src/types.ts
@@ -28,7 +28,6 @@ export interface FrontMatter {
 
 export interface SidebarOptions {
   fullNames?: boolean;
-  sidebarFile: string; //deprecated
   categoryLabel: string;
   indexLabel?: string;
   readmeLabel?: string;

diff --git a/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/options.spec.ts.snap b/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/options.spec.ts.snap
@@ -7,7 +7,6 @@ Object {
   "indexLabel": "Custom index",
   "position": null,
   "readmeLabel": "Custom readme",
-  "sidebarFile": "custom-sidebar.js",
 }
 `;
 
@@ -38,7 +37,6 @@ Object {
     "indexLabel": undefined,
     "position": null,
     "readmeLabel": "Readme",
-    "sidebarFile": "typedoc-sidebar.js",
   },
   "watch": false,
 }

diff --git a/packages/docusaurus-plugin-typedoc/test/specs/options.spec.ts b/packages/docusaurus-plugin-typedoc/test/specs/options.spec.ts
@@ -19,7 +19,6 @@ describe(`Options:`, () => {
     expect(
       getPluginOptions({
         sidebar: {
-          sidebarFile: 'custom-sidebar.js',
           fullNames: true,
           indexLabel: 'Custom index',
           readmeLabel: 'Custom readme',