Skip to content

Commit b20c708

Browse files
sean-perkinssean-perkins
authored
feat: docusaurus v3 support (#266)
1 parent c838e1f commit b20c708

24 files changed

Lines changed: 4706 additions & 3304 deletions

File tree

‎demo/docusaurus.config.js‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
// @ts-check
2-
// Note: type annotations allow type checking and IDEs autocompletion
2+
// `@type` JSDoc annotations allow editor autocompletion and type checking
3+
// (when paired with `@ts-check`).
4+
// There are various equivalent ways to declare your Docusaurus config.
5+
// See: https://docusaurus.io/docs/api/docusaurus-config
36

4-
const lightCodeTheme = require("prism-react-renderer/themes/github");
5-
const darkCodeTheme = require("prism-react-renderer/themes/dracula");
7+
import { themes as prismThemes } from "prism-react-renderer";
68

79
/** @type {import('@docusaurus/types').Config} */
810
const config = {
@@ -113,8 +115,8 @@ const config = {
113115
copyright: `Copyright © ${new Date().getFullYear()} Cloud Annotations. Built with Docusaurus.`,
114116
},
115117
prism: {
116-
theme: lightCodeTheme,
117-
darkTheme: darkCodeTheme,
118+
theme: prismThemes.github,
119+
darkTheme: prismThemes.dracula,
118120
},
119121
api: {
120122
authPersistance: "localStorage",
@@ -123,4 +125,4 @@ const config = {
123125
}),
124126
};
125127

126-
module.exports = config;
128+
export default config;

‎demo/package.json‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,14 @@
1414
"write-heading-ids": "docusaurus write-heading-ids"
1515
},
1616
"dependencies": {
17-
"@docusaurus/core": "^2.0.0",
18-
"@mdx-js/react": "^1.6.22",
17+
"@docusaurus/core": "^3.0.0",
1918
"@svgr/webpack": "^5.5.0",
20-
"clsx": "^1.1.1",
19+
"clsx": "^1.2.1",
2120
"docusaurus-preset-openapi": "^0.6.4",
2221
"file-loader": "^6.2.0",
23-
"prism-react-renderer": "^1.2.1",
24-
"react": "^17.0.2",
25-
"react-dom": "^17.0.2",
22+
"prism-react-renderer": "^2.1.0",
23+
"react": "^18.0.0",
24+
"react-dom": "^18.0.0",
2625
"url-loader": "^4.1.1"
2726
},
2827
"browserslist": {

‎demo/sidebars.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,4 @@ const sidebars = {
2828
*/
2929
};
3030

31-
module.exports = sidebars;
31+
export default sidebars;

‎package.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@
3838
"@babel/preset-typescript": "^7.16.0",
3939
"@testing-library/cypress": "^8.0.1",
4040
"@types/jest": "^27.0.2",
41-
"@types/node": "^17.0.2",
42-
"@typescript-eslint/eslint-plugin": "^4.0.0",
43-
"@typescript-eslint/parser": "^4.0.0",
41+
"@types/node": "^18.0.0",
42+
"@typescript-eslint/eslint-plugin": "^6.0.0",
43+
"@typescript-eslint/parser": "^6.0.0",
4444
"babel-eslint": "^10.0.0",
4545
"cross-env": "^7.0.3",
4646
"cypress": "^8.7.0",
@@ -66,7 +66,7 @@
6666
"start-server-and-test": "^1.14.0",
6767
"ts-jest": "^27.0.6",
6868
"ts-node": "^10.9.1",
69-
"typescript": "^4.7.4"
69+
"typescript": "^5.2.2"
7070
},
7171
"lint-staged": {
7272
"**/*": "prettier --write --ignore-unknown"

‎packages/create-docusaurus-openapi/package.json‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@
2323
},
2424
"license": "MIT",
2525
"dependencies": {
26-
"@docusaurus/logger": "^2.0.0",
26+
"@docusaurus/logger": "^3.0.0",
2727
"commander": "^5.1.0",
28-
"fs-extra": "^10.0.0",
28+
"fs-extra": "^11.0.0",
2929
"lodash": "^4.17.20",
3030
"prompts": "^2.4.1",
3131
"semver": "^7.3.4",
@@ -34,10 +34,11 @@
3434
"tslib": "^2.3.1"
3535
},
3636
"engines": {
37-
"node": ">=14"
37+
"node": ">=18"
3838
},
3939
"devDependencies": {
4040
"@types/prompts": "^2.0.9",
41+
"@types/fs-extra": "^11.0.0",
4142
"@types/shelljs": "^0.8.6",
4243
"@types/supports-color": "^8.1.1"
4344
}

‎packages/docusaurus-plugin-openapi/package.json‎

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -21,39 +21,37 @@
2121
"watch": "tsc --watch"
2222
},
2323
"devDependencies": {
24-
"@docusaurus/module-type-aliases": "^2.0.0",
25-
"@docusaurus/types": "^2.0.0",
24+
"@docusaurus/module-type-aliases": "^3.0.0",
25+
"@docusaurus/types": "^3.0.0",
2626
"@types/axios": "^0.14.0",
27-
"@types/fs-extra": "^9.0.13",
2827
"@types/js-yaml": "^4.0.5",
2928
"@types/json-schema": "^7.0.9",
3029
"@types/lodash": "^4.14.176",
3130
"@types/postman-collection": "^3.5.3",
3231
"utility-types": "^3.10.0"
3332
},
3433
"dependencies": {
35-
"@docusaurus/mdx-loader": "^2.0.0",
36-
"@docusaurus/plugin-content-docs": "^2.0.0",
37-
"@docusaurus/utils": "^2.0.0",
38-
"@docusaurus/utils-validation": "^2.0.0",
34+
"@docusaurus/mdx-loader": "^3.0.0",
35+
"@docusaurus/plugin-content-docs": "^3.0.0",
36+
"@docusaurus/utils": "^3.0.0",
37+
"@docusaurus/utils-validation": "^3.0.0",
3938
"axios": "^0.26.1",
4039
"chalk": "^4.1.2",
41-
"clsx": "^1.1.1",
42-
"fs-extra": "^9.0.1",
40+
"clsx": "^1.2.1",
4341
"js-yaml": "^4.1.0",
4442
"json-refs": "^3.0.15",
4543
"json-schema-resolve-allof": "^1.5.0",
4644
"lodash": "^4.17.20",
4745
"openapi-to-postmanv2": "^1.2.1",
4846
"postman-collection": "^4.1.0",
49-
"remark-admonitions": "^1.2.1",
50-
"webpack": "^5.73.0"
47+
"remark-directive": "^3.0.0",
48+
"webpack": "^5.88.1"
5149
},
5250
"peerDependencies": {
53-
"react": "^16.8.4 || ^17.0.0",
54-
"react-dom": "^16.8.4 || ^17.0.0"
51+
"react": "^18.0.0",
52+
"react-dom": "^18.0.0"
5553
},
5654
"engines": {
57-
"node": ">=14"
55+
"node": ">=18"
5856
}
5957
}

‎packages/docusaurus-plugin-openapi/src/docs/docs.ts‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -117,11 +117,7 @@ async function doProcessDocMetadata({
117117
return sourceDirName;
118118
}
119119

120-
const unversionedId = [computeDirNameIdPrefix(), baseID]
121-
.filter(Boolean)
122-
.join("/");
123-
124-
const id = unversionedId;
120+
const id = [computeDirNameIdPrefix(), baseID].filter(Boolean).join("/");
125121

126122
const docSlug = getSlug({
127123
baseID,
@@ -145,12 +141,13 @@ async function doProcessDocMetadata({
145141

146142
const draft = isDraftForEnvironment({ env, frontMatter });
147143

144+
const unlisted = frontMatter.unlisted ?? false;
145+
148146
// Assign all of object properties during instantiation (if possible) for
149147
// NodeJS optimization.
150148
// Adding properties to object after instantiation will cause hidden
151149
// class transitions.
152150
return {
153-
unversionedId,
154151
id,
155152
title,
156153
description,
@@ -164,6 +161,7 @@ async function doProcessDocMetadata({
164161
version: "",
165162
sidebarPosition,
166163
frontMatter,
164+
unlisted,
167165
};
168166
}
169167

‎packages/docusaurus-plugin-openapi/src/index.ts‎

Lines changed: 13 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@
55
* LICENSE file in the root directory of this source tree.
66
* ========================================================================== */
77

8-
import path from "path";
8+
import { readFile } from "node:fs/promises";
9+
import { join, relative, resolve } from "node:path";
910

1011
import type {
1112
LoadContext,
@@ -23,7 +24,6 @@ import {
2324
Globby,
2425
} from "@docusaurus/utils";
2526
import chalk from "chalk";
26-
import fs from "fs-extra";
2727
import { Configuration } from "webpack";
2828

2929
import { DocEnv, processDocMetadata } from "./docs/docs";
@@ -37,23 +37,23 @@ export default function pluginOpenAPI(
3737
context: LoadContext,
3838
options: PluginOptions
3939
): Plugin<LoadedContent> {
40-
const { baseUrl, generatedFilesDir, siteDir } = context;
40+
const { baseUrl, generatedFilesDir, siteDir, siteConfig } = context;
4141

4242
const pluginId = options.id ?? DEFAULT_PLUGIN_ID;
4343

44-
const pluginDataDirRoot = path.join(
44+
const pluginDataDirRoot = join(
4545
generatedFilesDir,
4646
"docusaurus-plugin-openapi"
4747
);
4848

49-
const dataDir = path.join(pluginDataDirRoot, pluginId);
49+
const dataDir = join(pluginDataDirRoot, pluginId);
5050

5151
const aliasedSource = (source: string) =>
52-
`~api/${posixPath(path.relative(pluginDataDirRoot, source))}`;
52+
`~api/${posixPath(relative(pluginDataDirRoot, source))}`;
5353

5454
const contentPath = isURL(options.path)
5555
? options.path
56-
: path.resolve(context.siteDir, options.path);
56+
: resolve(context.siteDir, options.path);
5757

5858
return {
5959
name: "docusaurus-plugin-openapi",
@@ -70,8 +70,8 @@ export default function pluginOpenAPI(
7070
/** E.g. "api/plugins/myDoc.mdx" */
7171
relativeSource: string
7272
): Promise<MdxPageMetadata> {
73-
const source = path.join(contentPath, relativeSource);
74-
const content = await fs.readFile(source, "utf-8");
73+
const source = join(contentPath, relativeSource);
74+
const content = await readFile(source, "utf-8");
7575

7676
return {
7777
type: "mdx",
@@ -200,7 +200,7 @@ export default function pluginOpenAPI(
200200
exact: true,
201201
modules: {
202202
// TODO: "-content" should be inside hash to prevent name too long errors.
203-
content: path.join(dataDir, `${docuHash(pageId)}-content.mdx`),
203+
content: join(dataDir, `${docuHash(pageId)}-content.mdx`),
204204
},
205205
sidebar: sidebarName,
206206
};
@@ -237,6 +237,7 @@ export default function pluginOpenAPI(
237237
modules: {
238238
apiMetadata: aliasedSource(apiBaseMetadataPath),
239239
},
240+
priority: 999999,
240241
});
241242

242243
return;
@@ -274,19 +275,15 @@ export default function pluginOpenAPI(
274275
rehypePlugins,
275276
beforeDefaultRehypePlugins,
276277
beforeDefaultRemarkPlugins,
277-
// Docusaurus 2.2.0 has a regression that requires this option to be set.
278-
markdownConfig: {},
278+
markdownConfig: siteConfig.markdown ?? { mdx1Compat: {} },
279279
metadataPath: (mdxPath: string) => {
280280
if (mdxPath.startsWith(dataDir)) {
281281
// The MDX file already lives in `dataDir`: this is an OpenAPI MDX
282282
return mdxPath.replace(/(-content\.mdx?)$/, ".json");
283283
} else {
284284
// Standard resolution
285285
const aliasedSource = aliasedSitePath(mdxPath, siteDir);
286-
return path.join(
287-
dataDir,
288-
`${docuHash(aliasedSource)}.json`
289-
);
286+
return join(dataDir, `${docuHash(aliasedSource)}.json`);
290287
}
291288
},
292289
},

‎packages/docusaurus-plugin-openapi/src/markdown/createDescription.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,6 @@ export function createDescription(description: string | undefined) {
99
if (!description) {
1010
return "";
1111
}
12-
return `\n\n${description}\n\n`;
12+
// Replace usages of <= or >= with \<= or \>= to avoid MDX3 parsing issues.
13+
return `\n\n${description.replace(/([<>]=?)/g, "\\$1")}\n\n`;
1314
}

‎packages/docusaurus-plugin-openapi/src/markdown/createVersionBadge.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
* LICENSE file in the root directory of this source tree.
66
* ========================================================================== */
77

8+
import { escape } from "lodash";
9+
810
import { create, guard } from "./utils";
911

1012
export function createVersionBadge(version: string | undefined) {

0 commit comments

Comments
 (0)