Support for Docusaurus v3

[kamranayub]

Since we are migrating to Docusaurus, it makes sense to start with v3 (released on 10/31).

I'll use this issue to document any problems for the upgrade, and I can also try to address them in a PR.

Patches

Here is what seems to work, based on my notes below. The @theme/DocVersionRoot actually renders the routes which means it needs to be a parent route. The docs plugin does this automatically, so I had to update the index.ts logic to emulate that.

In addition, I changed @theme/DocPage to @theme/DocRoot and added @theme/DocsRoot as a parent route as well.

diff --git a/node_modules/docusaurus-plugin-typedoc-api/lib/components/ApiPage.js b/node_modules/docusaurus-plugin-typedoc-api/lib/components/ApiPage.js
index 7b40f71..89e6bad 100644
--- a/node_modules/docusaurus-plugin-typedoc-api/lib/components/ApiPage.js
+++ b/node_modules/docusaurus-plugin-typedoc-api/lib/components/ApiPage.js
@@ -6,13 +6,13 @@ function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) r
 require('@vscode/codicons/dist/codicon.css');
 require('../../assets/styles-8ad572ec.css');
 const React = require('react');
-const DocPage = require('@theme/DocPage');
+const DocRoot = require('@theme/DocRoot');
 const ApiDataContext = require('./ApiDataContext.js');
 const _interopDefault = e => e && e.__esModule ? e : {
   default: e
 };
 const React__default = /*#__PURE__*/_interopDefault(React);
-const DocPage__default = /*#__PURE__*/_interopDefault(DocPage);
+const DocRoot__default = /*#__PURE__*/_interopDefault(DocRoot);

 /* eslint-disable no-param-reassign */

@@ -64,7 +64,7 @@ function ApiPage(_ref) {
     value: value
   }, /*#__PURE__*/React__default.default.createElement("div", {
     className: "apiPage"
-  }, /*#__PURE__*/React__default.default.createElement(DocPage__default.default, props)));
+  }, /*#__PURE__*/React__default.default.createElement(DocRoot__default.default, props)));
 }
 module.exports = ApiPage;
 //# sourceMappingURL=ApiPage.js.map
diff --git a/node_modules/docusaurus-plugin-typedoc-api/lib/index.js b/node_modules/docusaurus-plugin-typedoc-api/lib/index.js
index 57a9cb7..2084e55 100644
--- a/node_modules/docusaurus-plugin-typedoc-api/lib/index.js
+++ b/node_modules/docusaurus-plugin-typedoc-api/lib/index.js
@@ -252,8 +252,7 @@ function typedocApiPlugin(context, pluginOptions) {
             component: path__default.default.join(__dirname, './components/ApiIndex.js'),
             modules: {
               options: optionsData,
-              packages: packagesData,
-              versionMetadata
+              packages: packagesData
             },
             sidebar: 'api'
           });
@@ -261,14 +260,30 @@ function typedocApiPlugin(context, pluginOptions) {
         addRoute({
           path: indexPermalink,
           exact: false,
-          component: path__default.default.join(__dirname, './components/ApiPage.js'),
-          routes,
-          modules: {
-            options: optionsData,
-            packages: packagesData,
-            versionMetadata
-          },
-          priority: loadedVersion.routePriority
+          component: '@theme/DocsRoot',
+          routes: [
+            {
+              path: indexPermalink,
+              exact: false,
+              component: '@theme/DocVersionRoot',
+              modules: {
+                version: versionMetadata
+              },
+              routes: [
+                {
+                  path: indexPermalink,
+                  exact: false,
+                  component: path__default.default.join(__dirname, './components/ApiPage.js'),
+                  routes,
+                  modules: {
+                    options: optionsData,
+                    packages: packagesData
+                  },
+                  priority: loadedVersion.routePriority
+                }
+              ]
+            }
+          ],
         });
       }));
     },

---

@theme/DocPage swizzle looks broken

Due to: https://docusaurus.io/docs/next/migration/v3#docs-theme-refactoring

I get this error:

Module not found: Error: Can't resolve '@theme/DocPage' in '...\node_modules\docusaurus-plugin-typedoc-api\lib\components

Needs @theme/DocVersionRoot support

It looks like the DocVersionRoot is now the new root component for pages. It needs a version prop passed to it, which looks like the docs plugin does here:

https://github.com/facebook/docusaurus/pull/7966/files#diff-62e560c4a02776e8ff2b50e50a98b8019332de40e4bb851bf9dc0c29c2e04d91R185-R202

Update deps and peerDeps

Will have to make changes to the package. Not sure if this will limit TypeDoc version support.

{
  "name": "docusaurus-plugin-typedoc-api",
  "version": "3.0.1",
  "description": "Docusaurus plugin that provides source code API documentation powered by TypeDoc. ",
  "keywords": [
    "docusaurus",
    "plugin",
    "typedoc",
    "api"
  ],
  "repository": {
    "type": "git",
    "url": "git@github.com:milesj/docusaurus-plugin-typedoc-api.git"
  },
  "author": "Miles Johnson",
  "license": "MIT",
  "main": "./lib/index.js",
  "types": "./lib/index.d.ts",
  "files": [
    "assets/**/*",
    "lib/**/*",
    "src/**/*",
    "styles.css"
  ],
  "engines": {
    "node": ">=18.0"
  },
  "funding": {
    "type": "ko-fi",
    "url": "https://ko-fi.com/milesjohnson"
  },
  "packemon": {
    "format": "lib",
    "platform": "node",
    "externals": [
      "@theme/*",
      "@docusaurus/*",
      "@vscode/*",
      "css$"
    ]
  },
  "peerDependencies": {
    "@docusaurus/core": "^3.0.0",
    "react": ">=18.0.0",
    "typescript": "^4.0.0 || ^5.0.0"
  },
  "dependencies": {
    "@docusaurus/plugin-content-docs": "^3.0.0",
    "@docusaurus/types": "^3.0.0",
    "@docusaurus/utils": "^3.0.0",
    "@vscode/codicons": "^0.0.33",
    "marked": "^4.3.0",
    "typedoc": "0.25.0"
  },
  "devDependencies": {
    "@docusaurus/module-type-aliases": "^3.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "typescript": "^5.2.2"
  },
  "gitHead": "a454145314aad61322aadd9ecc1a78f09e52018c"
}

Duplicate key errors

Locally with these changes I'm seeing some children key errors, but I haven't confirmed if I see the same thing with the Docusaurus v2.

[milesj]

I'll look into this today since I have some downtime

[milesj]

I've got the basics working here: https://github.com/milesj/docusaurus-plugin-typedoc-api/pull/115

If you want to pull it down and try it out.