feat(docusaurus): decouple typedoc logic into dedicated "typedoc-docusaurus-theme" plugin

Author: tgreyuk

.github/workflows/ci.typedoc-docusaurus-theme.yml

@@ -0,0 +1,41 @@
+name: CI [typedoc-docusaurus-theme]
+on:
+  push:
+    paths:
+      - 'packages/typedoc-docusaurus-theme/**'
+      - '!packages/typedoc-docusaurus-theme/README.md'
+      - '!packages/typedoc-docusaurus-theme/CHANGELOG.md'
+      - '!packages/typedoc-docusaurus-theme/package.json'
+    branches:
+      - main
+      - release
+      - beta
+  pull_request:
+    paths:
+      - 'packages/typedoc-docusaurus-theme/**'
+      - '!packages/typedoc-docusaurus-theme/README.md'
+      - '!packages/typedoc-docusaurus-theme/CHANGELOG.md'
+      - '!packages/typedoc-docusaurus-theme/package.json'
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: ['18']
+    name: Node ${{ matrix.node }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Set up Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+          cache: 'npm'
+      - name: Install
+        run: HUSKY=0 npm install
+      - name: Lint
+        run: npm run lint --workspace typedoc-docusaurus-theme
+      - name: Build
+        run: npm run build --workspace typedoc-plugin-markdown --workspace typedoc-docusaurus-theme
+      - name: Test
+        run: npm run test --workspace typedoc-docusaurus-theme

README.md

@@ -16,6 +16,7 @@ Please see [typedoc-plugin-markdown.org](https://typedoc-plugin-markdown.org).
 [typedoc-github-wiki-theme](./packages/typedoc-github-wiki-theme#readme) | [![npm](https://img.shields.io/npm/v/typedoc-github-wiki-theme.svg?logo=npm)](https://www.npmjs.com/package/typedoc-github-wiki-theme) | ![Downloads](https://img.shields.io/npm/dw/typedoc-github-wiki-theme?label=↓) | [Changelog](./packages/typedoc-github-wiki-theme/CHANGELOG.md) | 
 [typedoc-gitlab-wiki-theme](./packages/typedoc-gitlab-wiki-theme#readme) | [![npm](https://img.shields.io/npm/v/typedoc-gitlab-wiki-theme.svg?logo=npm)](https://www.npmjs.com/package/typedoc-gitlab-wiki-theme) | ![Downloads](https://img.shields.io/npm/dw/typedoc-gitlab-wiki-theme?label=↓) | [Changelog](./packages/typedoc-gitlab-wiki-theme/CHANGELOG.md) | 
 [typedoc-vitepress-theme](./packages/typedoc-vitepress-theme#readme) | [![npm](https://img.shields.io/npm/v/typedoc-vitepress-theme.svg?logo=npm)](https://www.npmjs.com/package/typedoc-vitepress-theme) | ![Downloads](https://img.shields.io/npm/dw/typedoc-vitepress-theme?label=↓) | [Changelog](./packages/typedoc-vitepress-theme/CHANGELOG.md) | 
+[typedoc-docusaurus-theme](./packages/typedoc-docusaurus-theme#readme) | [![npm](https://img.shields.io/npm/v/typedoc-docusaurus-theme.svg?logo=npm)](https://www.npmjs.com/package/typedoc-docusaurus-theme) | ![Downloads](https://img.shields.io/npm/dw/typedoc-docusaurus-theme?label=↓) | [Changelog](./packages/typedoc-docusaurus-theme/CHANGELOG.md) | 
 [docusaurus-plugin-typedoc](./packages/docusaurus-plugin-typedoc#readme) | [![npm](https://img.shields.io/npm/v/docusaurus-plugin-typedoc.svg?logo=npm)](https://www.npmjs.com/package/docusaurus-plugin-typedoc) | ![Downloads](https://img.shields.io/npm/dw/docusaurus-plugin-typedoc?label=↓) | [Changelog](./packages/docusaurus-plugin-typedoc/CHANGELOG.md) | 
 
 ## Contributing

devtools/examples/docusaurus-ts/docusaurus.config.ts

@@ -45,23 +45,28 @@ const config: Config = {
     [
       docusaurusPlugin,
       {
-        ...require(
-          path.join(
-            __dirname,
-            '../../../packages/typedoc-plugin-markdown/test/fixtures/typedoc.cjs',
-          ),
-        ),
-        tsconfig: path.join(
-          __dirname,
-          '../../../packages/typedoc-plugin-markdown/test/fixtures/tsconfig.json',
-        ),
-        entryPoints: [
-          '../../../packages/typedoc-plugin-markdown/test/fixtures/src/reflections/index.ts',
-        ],
+        tsconfig: './stubs/tsconfig.json',
+        entryPoints: ['./stubs/src/index.ts'],
+        readme: 'none',
+        cleanOutputDir: true,
+        logLevel: 'Warn',
+      },
+    ],
+    [
+      docusaurusPlugin,
+      {
+        id: 'api-2',
+        tsconfig: './stubs/tsconfig.json',
+        entryPoints: ['./stubs/src/index.ts'],
+        out: './docs/api-2',
+        readme: 'none',
         sidebar: {
           typescript: true,
           pretty: true,
+          deprecatedItemClassName: 'is-deprecated',
         },
+        logLevel: 'Warn',
+        plugin: ['./stubs/custom-plugin.mjs'],
       },
     ],
   ],
@@ -114,6 +119,12 @@ const config: Config = {
           label: 'API 1',
           position: 'left',
         },
+        {
+          to: 'docs/api-2',
+          activeBasePath: 'docs',
+          label: 'API 2',
+          position: 'left',
+        },
       ],
     },
     footer: {

devtools/examples/docusaurus-ts/package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "docusaurus": "docusaurus",
     "prestart": "rm -rf ./docs && cd ../../../packages/docusaurus-plugin-typedoc && npm run build",
+    "generate": "npm run prestart && docusaurus generate-typedoc",
     "start": "docusaurus start",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",

devtools/examples/docusaurus-ts/sidebars.ts

@@ -1,5 +1,5 @@
-import { SidebarsConfig } from '@docusaurus/plugin-content-docs';
-import typedocSidebar from './docs/api/typedoc-sidebar';
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+import typedocSidebar from './docs/api-2/typedoc-sidebar';
 
 const sidebars: SidebarsConfig = {
   typedocSidebar: [
@@ -8,7 +8,7 @@ const sidebars: SidebarsConfig = {
       label: 'Typedoc API',
       link: {
         type: 'doc',
-        id: 'api/index',
+        id: 'api-2/index',
       },
       items: typedocSidebar.items,
     },

devtools/examples/docusaurus-ts/stubs/custom-plugin.mjs

@@ -0,0 +1,12 @@
+// @ts-check
+import * as fs from 'fs';
+import { MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+
+export function load(app) {
+  app.renderer.on(MarkdownRendererEvent.END, (renderer) => {
+    fs.writeFileSync(
+      `${renderer.outputDirectory}/custom-plugin.txt`,
+      'custom-plugin',
+    );
+  });
+}

packages/docusaurus-plugin-typedoc/test/stubs/src/links.ts renamed to devtools/examples/docusaurus-ts/stubs/src/index.ts

@@ -8,7 +8,9 @@
     "strict": true,
     "noUnusedLocals": false,
     "noUnusedParameters": false,
-    "target": "es2022"
+    "target": "es2022",
+    "jsx": "react",
+    "types": ["node", "react"]
   },
   "include": ["./src/*.ts"]
 }

packages/docusaurus-plugin-typedoc/test/stubs/tsconfig.json renamed to devtools/examples/docusaurus-ts/stubs/tsconfig.json

@@ -51,12 +51,15 @@ export const DOCS_CONFIG: Record<string, DocsConfig> = {
     declarations: true,
     presets: true,
   },
-  ['docusaurus-plugin-typedoc']: {
+  ['typedoc-docusaurus-theme']: {
     declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     presetsPath: `${process.cwd()}/src/options/presets.ts`,
-    optionsPath: '/plugins/docusaurus',
+    optionsPath: 'plugins/docusaurus',
     docsPath: '/plugins/docusaurus',
     declarations: true,
     presets: true,
   },
+  ['docusaurus-plugin-typedoc']: {
+    docsPath: '/plugins/docusaurus',
+  },
 };

devtools/packages/helpers/constants.ts

@@ -2,11 +2,11 @@ export interface DocsConfig {
   declarationsPath?: string;
   translatablePath?: string;
   presetsPath?: string;
-  optionsPath: string;
+  optionsPath?: string;
   optionsFile?: string;
   docsPath: string;
-  declarations: boolean;
-  presets: boolean;
+  declarations?: boolean;
+  presets?: boolean;
   categories?: Record<string, string>;
 }
 

devtools/packages/helpers/models.ts

@@ -12,6 +12,7 @@ async function main() {
     'typedoc-github-wiki-theme',
     'typedoc-gitlab-wiki-theme',
     'typedoc-vitepress-theme',
+    'typedoc-docusaurus-theme',
     'docusaurus-plugin-typedoc',
   ].map(async (packageName) => {
     const packageJson = await import(

devtools/scripts/generate-readmes.ts

@@ -1,5 +1,3 @@
-import { Callout, Steps } from 'nextra/components';
-
 # Quick Start
 
 ## Installation
@@ -31,6 +29,6 @@ Or:
 }
 ```
 
-```shell filename="CLI"
+```bash filename="CLI"
 npm run docs
 ```

docs/content/docs/quick-start.mdx

@@ -13,9 +13,5 @@ export default {
   'github-wiki': 'Github Wiki',
   'gitlab-wiki': 'Gitlab Wiki',
   vitepress: 'VitePress',
-  '-- Integrations': {
-    type: 'separator',
-    title: 'Integrations',
-  },
   docusaurus: 'Docusaurus',
 };

docs/content/plugins/_meta.js

@@ -2,14 +2,15 @@
 asIndexPage: true
 ---
 
-import { Cards } from 'nextra/components';
-import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+{/* prettier-ignore */}
 import { faGithub } from '@fortawesome/free-brands-svg-icons';
 import { faGlobe } from '@fortawesome/free-solid-svg-icons';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import { Cards } from 'nextra/components';
 
-# docusaurus-plugin-typedoc
+# typedoc-docusaurus-theme
 
-<PackageVersion name={'docusaurus-plugin-typedoc'} />
+<PackageVersion name={'typedoc-docusaurus-theme'} />
 
 ## Overview
 
@@ -20,8 +21,8 @@ It is a Docusaurus plugin (not a TypeDoc plugin) and is designed to work within
 ## Features
 
 - Presets relevant options of typedoc-plugin-markdown.
-- Bootstraps TypeDoc from the Docusaurus CLI.
-- Generates a sidebar file with configurable structure.
+- Generates a configurable docusaurus sidebar.
+- Use a Docusaurus plugin to bootstraps TypeDoc from the Docusaurus CLI.
 
 ## Example
 

docs/content/plugins/docusaurus/index.mdx

@@ -13,10 +13,10 @@ The following are preset typedoc-plugin-markdown options:
 
 ```json"
 {
-  "out": "./docs/api",
   "hideBreadcrumbs": true,
   "hidePageHeader": true,
-  "entryFileName": "index.md"
+  "entryFileName": "index.md",
+  "out": "docs/api"
 }
 ```
 
@@ -26,7 +26,7 @@ The following options are exposed by this plugin:
 
 ## sidebar
 
-<Callout emoji="💡">Configures the autogenerated Docusaurus sidebar.</Callout>
+<Callout emoji="💡">Configures the autogenerated sidebar.</Callout>
 
 > Accepts a key/value object.
 
@@ -48,20 +48,48 @@ The class name to apply to deprecated items in the sidebar. Defaults to `"typedo
 
 Please see the [sidebar guide](/plugins/docusaurus/guides/sidebar) for additional information on sidebar setup.
 
-```js filename="docusaurus.config.js"
+````js filename="docusaurus.config.js"
 {
   plugins: [
     [
       'docusaurus-plugin-typedoc',
       {
-        sidebar: {
-          autoConfiguration: true,
-          pretty: false,
-          typescript: false,
-          deprecatedItemClassName: 'typedoc-sidebar-item-deprecated',
-        },
-      },
-    ],
-  ];
+        "sidebar": {
+          "autoConfiguration": true,
+          "pretty": false,
+          "typescript": false,
+          "deprecatedItemClassName": "typedoc-sidebar-item-deprecated"
+        }
+      }
+    ]
+  ]
+}
+
+## docsPath
+
+<Callout emoji="💡">The path to docsPath.</Callout>
+
+> Defaults to `"./docs"`.
+
+This is the docs path for the generated docs.
+
+
+```json filename="typedoc.json"
+{
+  "docsPath": "./docs"
+}
+````
+
+## numberPrefixParser
+
+<Callout emoji="💡">The numberPrefixParser.</Callout>
+
+> Accepts a boolean value. Defaults to `false`.
+
+The equivalent number prefix parser.
+
+```json filename="typedoc.json"
+{
+  "numberPrefixParser": false
 }
 ```

docs/content/plugins/docusaurus/options.mdx

@@ -2,15 +2,21 @@ import { Callout, Steps, FileTree } from 'nextra/components';
 
 # Quick Start
 
-## Installation
+## Docusaurus Plugin (Recommended)
+
+For a minimal setup can bootstrap the theme with theme directly using the Docusaurus plugin `docusaurus-plugin-typedoc`.
+
+This means you can manage TypeDoc entirely within `docusaurus.config`.
+
+### Installation
 
 Install Docusaurus in the root of your project and install the plugin dependencies in the same location as the Docusaurus website directory.
 
 ```sh npm2yarn
 npm install typedoc typedoc-plugin-markdown docusaurus-plugin-typedoc --save-dev
 ```
 
-## Usage
+### Usage
 
 <Steps>
 
@@ -62,17 +68,39 @@ module.exports = {
 };
 ```
 
-### Run Docusaurus
+#### Run Docusaurus
 
 You can generate the docs by either:
 
 - Running Docusaurus by using the `start` or `build` [cli commands](https://docusaurus.io/docs/cli#docusaurus-cli-commands).
 - Building the docs independently by running the custom cli command `docusaurus generate-typedoc` and then running Docusaurus at another time.
 
-### View the docs
+#### View the docs
 
 Once built the docs will be available at `/docs/api` (or equivalent output directory).
 
 e.g. `http://localhost:3000/docs/api`
 
 </Steps>
+
+## Standalone
+
+If you would prefer to generate your docs entirely outside of a Docusaurus project, for later consumption you can simply run `typedoc-docusaurus-theme` independently.
+
+### Install
+
+```sh npm2yarn
+npm install typedoc typedoc-plugin-markdown typedoc-docusaurus-theme --save-dev
+```
+
+### Usage
+
+```json filename="typedoc.json"
+{
+  "plugin": ["typedoc-plugin-markdown", "typedoc-docusaurus-theme"]
+}
+```
+
+```bash filename="CLI"
+npm run typedoc
+```