feat: docusaurus v3 support (#266)

cloud-annotations · Dec 12, 2023 · b20c708 · b20c708
1 parent c838e1f
commit b20c708
Show file tree

Hide file tree

Showing 24 changed files with 4,706 additions and 3,304 deletions.
diff --git a/demo/docusaurus.config.js b/demo/docusaurus.config.js
@@ -1,8 +1,10 @@
 // @ts-check
-// Note: type annotations allow type checking and IDEs autocompletion
+// `@type` JSDoc annotations allow editor autocompletion and type checking
+// (when paired with `@ts-check`).
+// There are various equivalent ways to declare your Docusaurus config.
+// See: https://docusaurus.io/docs/api/docusaurus-config
 
-const lightCodeTheme = require("prism-react-renderer/themes/github");
-const darkCodeTheme = require("prism-react-renderer/themes/dracula");
+import { themes as prismThemes } from "prism-react-renderer";
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -113,8 +115,8 @@ const config = {
         copyright: `Copyright © ${new Date().getFullYear()} Cloud Annotations. Built with Docusaurus.`,
       },
       prism: {
-        theme: lightCodeTheme,
-        darkTheme: darkCodeTheme,
+        theme: prismThemes.github,
+        darkTheme: prismThemes.dracula,
       },
       api: {
         authPersistance: "localStorage",
@@ -123,4 +125,4 @@ const config = {
     }),
 };
 
-module.exports = config;
+export default config;
diff --git a/demo/package.json b/demo/package.json
@@ -14,15 +14,14 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.0.0",
-    "@mdx-js/react": "^1.6.22",
+    "@docusaurus/core": "^3.0.0",
     "@svgr/webpack": "^5.5.0",
-    "clsx": "^1.1.1",
+    "clsx": "^1.2.1",
     "docusaurus-preset-openapi": "^0.6.4",
     "file-loader": "^6.2.0",
-    "prism-react-renderer": "^1.2.1",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2",
+    "prism-react-renderer": "^2.1.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
     "url-loader": "^4.1.1"
   },
   "browserslist": {

diff --git a/demo/sidebars.js b/demo/sidebars.js
@@ -28,4 +28,4 @@ const sidebars = {
    */
 };
 
-module.exports = sidebars;
+export default sidebars;
diff --git a/package.json b/package.json
@@ -38,9 +38,9 @@
     "@babel/preset-typescript": "^7.16.0",
     "@testing-library/cypress": "^8.0.1",
     "@types/jest": "^27.0.2",
-    "@types/node": "^17.0.2",
-    "@typescript-eslint/eslint-plugin": "^4.0.0",
-    "@typescript-eslint/parser": "^4.0.0",
+    "@types/node": "^18.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
     "babel-eslint": "^10.0.0",
     "cross-env": "^7.0.3",
     "cypress": "^8.7.0",
@@ -66,7 +66,7 @@
     "start-server-and-test": "^1.14.0",
     "ts-jest": "^27.0.6",
     "ts-node": "^10.9.1",
-    "typescript": "^4.7.4"
+    "typescript": "^5.2.2"
   },
   "lint-staged": {
     "**/*": "prettier --write --ignore-unknown"

diff --git a/packages/create-docusaurus-openapi/package.json b/packages/create-docusaurus-openapi/package.json
@@ -23,9 +23,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "^2.0.0",
+    "@docusaurus/logger": "^3.0.0",
     "commander": "^5.1.0",
-    "fs-extra": "^10.0.0",
+    "fs-extra": "^11.0.0",
     "lodash": "^4.17.20",
     "prompts": "^2.4.1",
     "semver": "^7.3.4",
@@ -34,10 +34,11 @@
     "tslib": "^2.3.1"
   },
   "engines": {
-    "node": ">=14"
+    "node": ">=18"
   },
   "devDependencies": {
     "@types/prompts": "^2.0.9",
+    "@types/fs-extra": "^11.0.0",
     "@types/shelljs": "^0.8.6",
     "@types/supports-color": "^8.1.1"
   }

diff --git a/packages/docusaurus-plugin-openapi/package.json b/packages/docusaurus-plugin-openapi/package.json
@@ -21,39 +21,37 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^2.0.0",
-    "@docusaurus/types": "^2.0.0",
+    "@docusaurus/module-type-aliases": "^3.0.0",
+    "@docusaurus/types": "^3.0.0",
     "@types/axios": "^0.14.0",
-    "@types/fs-extra": "^9.0.13",
     "@types/js-yaml": "^4.0.5",
     "@types/json-schema": "^7.0.9",
     "@types/lodash": "^4.14.176",
     "@types/postman-collection": "^3.5.3",
     "utility-types": "^3.10.0"
   },
   "dependencies": {
-    "@docusaurus/mdx-loader": "^2.0.0",
-    "@docusaurus/plugin-content-docs": "^2.0.0",
-    "@docusaurus/utils": "^2.0.0",
-    "@docusaurus/utils-validation": "^2.0.0",
+    "@docusaurus/mdx-loader": "^3.0.0",
+    "@docusaurus/plugin-content-docs": "^3.0.0",
+    "@docusaurus/utils": "^3.0.0",
+    "@docusaurus/utils-validation": "^3.0.0",
     "axios": "^0.26.1",
     "chalk": "^4.1.2",
-    "clsx": "^1.1.1",
-    "fs-extra": "^9.0.1",
+    "clsx": "^1.2.1",
     "js-yaml": "^4.1.0",
     "json-refs": "^3.0.15",
     "json-schema-resolve-allof": "^1.5.0",
     "lodash": "^4.17.20",
     "openapi-to-postmanv2": "^1.2.1",
     "postman-collection": "^4.1.0",
-    "remark-admonitions": "^1.2.1",
-    "webpack": "^5.73.0"
+    "remark-directive": "^3.0.0",
+    "webpack": "^5.88.1"
   },
   "peerDependencies": {
-    "react": "^16.8.4 || ^17.0.0",
-    "react-dom": "^16.8.4 || ^17.0.0"
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
   },
   "engines": {
-    "node": ">=14"
+    "node": ">=18"
   }
 }
diff --git a/packages/docusaurus-plugin-openapi/src/docs/docs.ts b/packages/docusaurus-plugin-openapi/src/docs/docs.ts
@@ -117,11 +117,7 @@ async function doProcessDocMetadata({
     return sourceDirName;
   }
 
-  const unversionedId = [computeDirNameIdPrefix(), baseID]
-    .filter(Boolean)
-    .join("/");
-
-  const id = unversionedId;
+  const id = [computeDirNameIdPrefix(), baseID].filter(Boolean).join("/");
 
   const docSlug = getSlug({
     baseID,
@@ -145,12 +141,13 @@ async function doProcessDocMetadata({
 
   const draft = isDraftForEnvironment({ env, frontMatter });
 
+  const unlisted = frontMatter.unlisted ?? false;
+
   // Assign all of object properties during instantiation (if possible) for
   // NodeJS optimization.
   // Adding properties to object after instantiation will cause hidden
   // class transitions.
   return {
-    unversionedId,
     id,
     title,
     description,
@@ -164,6 +161,7 @@ async function doProcessDocMetadata({
     version: "",
     sidebarPosition,
     frontMatter,
+    unlisted,
   };
 }
 

diff --git a/packages/docusaurus-plugin-openapi/src/index.ts b/packages/docusaurus-plugin-openapi/src/index.ts
@@ -5,7 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import path from "path";
+import { readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
 
 import type {
   LoadContext,
@@ -23,7 +24,6 @@ import {
   Globby,
 } from "@docusaurus/utils";
 import chalk from "chalk";
-import fs from "fs-extra";
 import { Configuration } from "webpack";
 
 import { DocEnv, processDocMetadata } from "./docs/docs";
@@ -37,23 +37,23 @@ export default function pluginOpenAPI(
   context: LoadContext,
   options: PluginOptions
 ): Plugin<LoadedContent> {
-  const { baseUrl, generatedFilesDir, siteDir } = context;
+  const { baseUrl, generatedFilesDir, siteDir, siteConfig } = context;
 
   const pluginId = options.id ?? DEFAULT_PLUGIN_ID;
 
-  const pluginDataDirRoot = path.join(
+  const pluginDataDirRoot = join(
     generatedFilesDir,
     "docusaurus-plugin-openapi"
   );
 
-  const dataDir = path.join(pluginDataDirRoot, pluginId);
+  const dataDir = join(pluginDataDirRoot, pluginId);
 
   const aliasedSource = (source: string) =>
-    `~api/${posixPath(path.relative(pluginDataDirRoot, source))}`;
+    `~api/${posixPath(relative(pluginDataDirRoot, source))}`;
 
   const contentPath = isURL(options.path)
     ? options.path
-    : path.resolve(context.siteDir, options.path);
+    : resolve(context.siteDir, options.path);
 
   return {
     name: "docusaurus-plugin-openapi",
@@ -70,8 +70,8 @@ export default function pluginOpenAPI(
         /** E.g. "api/plugins/myDoc.mdx" */
         relativeSource: string
       ): Promise<MdxPageMetadata> {
-        const source = path.join(contentPath, relativeSource);
-        const content = await fs.readFile(source, "utf-8");
+        const source = join(contentPath, relativeSource);
+        const content = await readFile(source, "utf-8");
 
         return {
           type: "mdx",
@@ -200,7 +200,7 @@ export default function pluginOpenAPI(
           exact: true,
           modules: {
             // TODO: "-content" should be inside hash to prevent name too long errors.
-            content: path.join(dataDir, `${docuHash(pageId)}-content.mdx`),
+            content: join(dataDir, `${docuHash(pageId)}-content.mdx`),
           },
           sidebar: sidebarName,
         };
@@ -237,6 +237,7 @@ export default function pluginOpenAPI(
         modules: {
           apiMetadata: aliasedSource(apiBaseMetadataPath),
         },
+        priority: 999999,
       });
 
       return;
@@ -274,19 +275,15 @@ export default function pluginOpenAPI(
                     rehypePlugins,
                     beforeDefaultRehypePlugins,
                     beforeDefaultRemarkPlugins,
-                    // Docusaurus 2.2.0 has a regression that requires this option to be set.
-                    markdownConfig: {},
+                    markdownConfig: siteConfig.markdown ?? { mdx1Compat: {} },
                     metadataPath: (mdxPath: string) => {
                       if (mdxPath.startsWith(dataDir)) {
                         // The MDX file already lives in `dataDir`: this is an OpenAPI MDX
                         return mdxPath.replace(/(-content\.mdx?)$/, ".json");
                       } else {
                         // Standard resolution
                         const aliasedSource = aliasedSitePath(mdxPath, siteDir);
-                        return path.join(
-                          dataDir,
-                          `${docuHash(aliasedSource)}.json`
-                        );
+                        return join(dataDir, `${docuHash(aliasedSource)}.json`);
                       }
                     },
                   },

diff --git a/packages/docusaurus-plugin-openapi/src/markdown/createDescription.ts b/packages/docusaurus-plugin-openapi/src/markdown/createDescription.ts
@@ -9,5 +9,6 @@ export function createDescription(description: string | undefined) {
   if (!description) {
     return "";
   }
-  return `\n\n${description}\n\n`;
+  // Replace usages of <= or >= with \<= or \>= to avoid MDX3 parsing issues.
+  return `\n\n${description.replace(/([<>]=?)/g, "\\$1")}\n\n`;
 }
diff --git a/packages/docusaurus-plugin-openapi/src/markdown/createVersionBadge.ts b/packages/docusaurus-plugin-openapi/src/markdown/createVersionBadge.ts
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import { escape } from "lodash";
+
 import { create, guard } from "./utils";
 
 export function createVersionBadge(version: string | undefined) {

diff --git a/packages/docusaurus-plugin-openapi/src/markdown/utils.ts b/packages/docusaurus-plugin-openapi/src/markdown/utils.ts
@@ -17,7 +17,9 @@ export function create(tag: string, props: Props): string {
     propString += ` ${key}={${JSON.stringify(value)}}`;
   }
 
-  return `<${tag}${propString}>${render(children)}</${tag}>`;
+  return `<${tag}${propString}>
+  ${render(children)}
+</${tag}>`;
 }
 
 export function guard<T>(
@@ -33,7 +35,7 @@ export function guard<T>(
 
 export function render(children: Children): string {
   if (Array.isArray(children)) {
-    return children.filter((c) => c !== undefined).join("");
+    return children.filter((c) => c !== undefined).join("\n");
   }
   return children ?? "";
 }
diff --git a/packages/docusaurus-plugin-openapi/src/openapi/openapi.ts b/packages/docusaurus-plugin-openapi/src/openapi/openapi.ts
@@ -5,12 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import path from "path";
+import { lstat, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 
 import { aliasedSitePath, Globby, normalizeUrl } from "@docusaurus/utils";
 import axios from "axios";
 import chalk from "chalk";
-import fs from "fs-extra";
 import yaml from "js-yaml";
 import JsonRefs from "json-refs";
 import resolveAllOf from "json-schema-resolve-allof";
@@ -85,7 +85,6 @@ function createItems(openapiData: OpenApiObject): ApiMetadata[] {
     const infoPage: PartialPage<InfoPageMetadata> = {
       type: "info",
       id: "introduction",
-      unversionedId: "introduction",
       title: "Introduction",
       description: openapiData.info.description,
       slug: "/introduction",
@@ -144,7 +143,6 @@ function createItems(openapiData: OpenApiObject): ApiMetadata[] {
       const apiPage: PartialPage<ApiPageMetadata> = {
         type: "api",
         id: baseId,
-        unversionedId: baseId,
         title: title,
         description: description ?? "",
         slug: "/" + baseId,
@@ -225,7 +223,7 @@ export async function readOpenapiFiles(
       },
     ];
   }
-  const stat = await fs.lstat(openapiPath);
+  const stat = await lstat(openapiPath);
   if (stat.isDirectory()) {
     console.warn(
       chalk.yellow(
@@ -242,18 +240,18 @@ export async function readOpenapiFiles(
     return Promise.all(
       sources.map(async (source) => {
         // TODO: make a function for this
-        const fullPath = path.join(openapiPath, source);
-        const openapiString = await fs.readFile(fullPath, "utf-8");
+        const fullPath = join(openapiPath, source);
+        const openapiString = await readFile(fullPath, "utf-8");
         const data = yaml.load(openapiString) as OpenApiObjectWithRef;
         return {
           source: fullPath, // This will be aliased in process.
-          sourceDirName: path.dirname(source),
+          sourceDirName: dirname(source),
           data,
         };
       })
     );
   }
-  const openapiString = await fs.readFile(openapiPath, "utf-8");
+  const openapiString = await readFile(openapiPath, "utf-8");
   const data = yaml.load(openapiString) as OpenApiObjectWithRef;
   return [
     {
@@ -298,7 +296,6 @@ export async function processOpenapiFiles(
     }
 
     items[i].id = id;
-    items[i].unversionedId = id;
     items[i].slug = "/" + id;
   }
-Original file line number
+Diff line change
@@ Expand Up / @@ -28,4 +28,4 @@ const sidebars = { @@
        */
     };
-    module.exports = sidebars;
+    export default sidebars;