Upgrade to docusaurus 3.0 (#2628)

Docusaurus 3.0 was just released, this new version brings up - react 18 which allows us to not use an outdated version here - config can use typescript - some perf improvement(however we already were proactive so its not very noticable) https://docusaurus.io/blog/releases/3.0 Typespec azure PR https://github.com/Azure/typespec-azure/pull/3823
microsoft · Nov 6, 2023 · adba3b9 · adba3b9
1 parent af875c3
commit adba3b9
Show file tree

Hide file tree

Showing 28 changed files with 1,846 additions and 1,943 deletions.
diff --git a/common/config/rush/common-versions.json b/common/config/rush/common-versions.json
@@ -40,7 +40,5 @@
     // "typescript": [
     //   "~2.4.0"
     // ]
-    "react": ["^17.0.2"],
-    "react-dom": ["^17.0.2"]
   }
 }
diff --git a/common/config/rush/pnpm-config.json b/common/config/rush/pnpm-config.json
@@ -89,8 +89,6 @@
    * PNPM documentation: https://pnpm.io/package_json#pnpmoverrides
    */
   "globalOverrides": {
-    "[email protected]": "0.0.3",
-    "update-notifier@^5.1.0": "^6.0.2",
     "[email protected]": "^3.3.2"
     // "example1": "^1.0.0",
     // "example2": "npm:@company/example2@^1.0.0"

diff --git a/common/config/rush/pnpm-lock.yaml b/common/config/rush/pnpm-lock.yaml
diff --git a/docs/extending-typespec/basics.md b/docs/extending-typespec/basics.md
@@ -87,7 +87,7 @@ This will create `tsconfig.json`. But we need to make a couple changes to this.
 
 Open `./src/lib.ts` and create your library definition that registers your library with the TypeSpec compiler and defines any diagnostics your library will emit. Make sure to export the library definition as `$lib`.
 
-:::warn
+:::warning
 If `$lib` is not accessible from your library package (`import {$lib} from "my-library";`) some functionality will be unavailable like validation of emitter options, linter rules, etc.
 :::
 

diff --git a/docs/introduction/reproducibility.md b/docs/introduction/reproducibility.md
@@ -22,7 +22,7 @@ The command `npm ci` can also be used in the CI to ensure that the `package.json
 
 TypeSpec provides a library `@typespec/versioning` that can be used to describe changes to a service or library over time. Using this will ensure that a service can evolve while keeping track of the changes and allowing emitters to see the service representation at different versions.
 
-[See versioning docs](../standard-library/versioning/reference/index.md)
+[See versioning docs](../standard-library/versioning/reference/index.mdx)
 
 ## 3. Change to the TypeSpec spec
 
@@ -32,5 +32,5 @@ Using version control and pinning to a specific commit SHA will ensure that the
 ## Summary
 
 1. Use `package-lock.json`
-2. Use [versioning library](../standard-library/versioning/reference/index.md)
+2. Use [versioning library](../standard-library/versioning/reference/index.mdx)
 3. Keep track of commit IDs
diff --git a/.../standard-library/http/reference/index.md → ...standard-library/http/reference/index.mdx b/.../standard-library/http/reference/index.md → ...standard-library/http/reference/index.mdx
diff --git a/...rd-library/json-schema/reference/index.md → ...d-library/json-schema/reference/index.mdx b/...rd-library/json-schema/reference/index.md → ...d-library/json-schema/reference/index.mdx
diff --git a/...andard-library/openapi/reference/index.md → ...ndard-library/openapi/reference/index.mdx b/...andard-library/openapi/reference/index.md → ...ndard-library/openapi/reference/index.mdx
diff --git a/...ndard-library/openapi3/reference/index.md → ...dard-library/openapi3/reference/index.mdx b/...ndard-library/openapi3/reference/index.md → ...dard-library/openapi3/reference/index.mdx
diff --git a/...ndard-library/protobuf/reference/index.md → ...dard-library/protobuf/reference/index.mdx b/...ndard-library/protobuf/reference/index.md → ...dard-library/protobuf/reference/index.mdx
diff --git a/.../standard-library/rest/reference/index.md → ...standard-library/rest/reference/index.mdx b/.../standard-library/rest/reference/index.md → ...standard-library/rest/reference/index.mdx
diff --git a/...ard-library/versioning/reference/index.md → ...rd-library/versioning/reference/index.mdx b/...ard-library/versioning/reference/index.md → ...rd-library/versioning/reference/index.mdx
diff --git a/packages/tspd/src/ref-doc/emitters/docusaurus.ts b/packages/tspd/src/ref-doc/emitters/docusaurus.ts
@@ -21,7 +21,7 @@ import { MarkdownRenderer, groupByNamespace } from "./markdown.js";
 export function renderToDocusaurusMarkdown(refDoc: TypeSpecRefDoc): Record<string, string> {
   const renderer = new DocusaurusRenderer();
   const files: Record<string, string> = {
-    "index.md": renderIndexFile(renderer, refDoc),
+    "index.mdx": renderIndexFile(renderer, refDoc),
   };
 
   const decoratorFile = renderDecoratorFile(renderer, refDoc);

diff --git a/packages/website/docusaurus.config.js → packages/website/docusaurus.config.ts b/packages/website/docusaurus.config.js → packages/website/docusaurus.config.ts
@@ -1,12 +1,12 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 
-// const lightCodeTheme = require("prism-react-renderer/themes/github");
-const lightCodeTheme = require("./themes/prism/atom-one-light.js");
-const { themes } = require("prism-react-renderer");
+import type { VersionOptions } from "@docusaurus/plugin-content-docs";
+import type { Config } from "@docusaurus/types";
+import { themes } from "prism-react-renderer";
 const { resolve } = require("path");
 
-function getMajorMinorVersion(pkgJsonPath) {
+function getMajorMinorVersion(pkgJsonPath): string {
   const version = require(pkgJsonPath).version;
   const [major, minor] = version.split(".");
   return `${major}.${minor}.x`;
@@ -16,9 +16,8 @@ function getLatestVersion() {
   return `Latest (${getMajorMinorVersion("../compiler/package.json")})`;
 }
 
-/** @returns {Record<string, import('@docusaurus/plugin-content-docs').VersionOptions>} */
-function getVersionLabels() {
-  const labels = {
+function getVersionLabels(): Record<string, VersionOptions> {
+  const labels: Record<string, VersionOptions> = {
     current: {
       label: `Next 🚧`,
     },
@@ -34,8 +33,7 @@ function getVersionLabels() {
   return labels;
 }
 
-/** @type {import('@docusaurus/types').Config} */
-const config = {
+const config: Config = {
   title: "TypeSpec",
   tagline: "API first with TypeSpec for Azure services",
   url: "https://microsoft.github.io",
@@ -60,13 +58,14 @@ const config = {
 
   markdown: {
     mermaid: true,
+    format: "detect",
   },
   themes: ["@docusaurus/theme-mermaid"],
   presets: [
     [
       "classic",
       /** @type {import('@docusaurus/preset-classic').Options} */
-      ({
+      {
         docs: {
           routeBasePath: "/",
           sidebarPath: require.resolve("./sidebars.js"),
@@ -80,7 +79,7 @@ const config = {
         theme: {
           customCss: require.resolve("./src/css/custom.css"),
         },
-      }),
+      },
     ],
   ],
   staticDirectories: [resolve(__dirname, "./node_modules/@typespec/spec/dist")],
@@ -109,7 +108,7 @@ const config = {
   },
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
-    ({
+    {
       navbar: {
         title: "TypeSpec",
         items: [
@@ -170,7 +169,7 @@ const config = {
         copyright: `Copyright © ${new Date().getFullYear()} Microsoft Corp.`,
       },
       prism: {
-        theme: lightCodeTheme,
+        theme: themes.oneLight,
         darkTheme: themes.dracula,
         additionalLanguages: [],
       },
@@ -181,7 +180,7 @@ const config = {
         apiKey: "bae16ae67ddbe24e700ac20d192ad20f",
         indexName: "typespec",
       },
-    }),
+    },
 };
 
-module.exports = config;
+export default config;
diff --git a/packages/website/package.json b/packages/website/package.json
@@ -23,13 +23,14 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@docusaurus/core": "^2.2.0",
-    "@docusaurus/preset-classic": "^2.2.0",
-    "@docusaurus/theme-mermaid": "^2.2.0",
-    "@mdx-js/react": "^1.6.22",
-    "prism-react-renderer": "^2.0.6",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "@docusaurus/core": "^3.0.0",
+    "@docusaurus/preset-classic": "^3.0.0",
+    "@docusaurus/theme-mermaid": "^3.0.0",
+    "@docusaurus/plugin-content-docs": "~3.0.0",
+    "@mdx-js/react": "^3.0.0",
+    "prism-react-renderer": "^2.1.0",
+    "react": "~18.2.0",
+    "react-dom": "~18.2.0"
   },
   "devDependencies": {
     "@swc/core": "^1.3.62",
@@ -43,15 +44,14 @@
     "@typespec/protobuf": "workspace:~0.49.0",
     "@typespec/versioning": "workspace:~0.49.0",
     "@typespec/json-schema": "workspace:~0.49.0",
-    "@docusaurus/module-type-aliases": "^2.4.3",
-    "@docusaurus/types": "^2.4.3",
-    "@tsconfig/docusaurus": "^2.0.1",
+    "@docusaurus/module-type-aliases": "^3.0.0",
+    "@docusaurus/types": "^3.0.0",
+    "@docusaurus/tsconfig": "^3.0.0",
     "typescript": "~5.2.2",
     "@types/node": "~18.11.9",
     "prism-themes": "~1.9.0",
     "playwright": "^1.39.0",
     "mermaid": "~10.4.0",
-    "mdx-mermaid": "2.0.0",
     "@typespec/eslint-config-typespec": "workspace:~0.49.0",
     "eslint": "^8.49.0",
     "rimraf": "~5.0.1",

diff --git a/packages/website/sidebars.js → packages/website/sidebars.ts b/packages/website/sidebars.js → packages/website/sidebars.ts
@@ -1,12 +1,11 @@
-// @ts-check
+import { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+import { SidebarItemConfig } from "@docusaurus/plugin-content-docs/src/sidebars/types.js";
 
-/**
- *
- * @param {string} libName
- * @param {any[]} [extra]
- * @returns {any}
- */
-function createLibraryReferenceStructure(libName, labelName, extra) {
+function createLibraryReferenceStructure(
+  libName: string,
+  labelName: string,
+  extra: SidebarItemConfig[]
+): SidebarItemConfig {
   return {
     type: "category",
     label: labelName,
@@ -24,8 +23,7 @@ function createLibraryReferenceStructure(libName, labelName, extra) {
   };
 }
 
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
-const sidebars = {
+const sidebars: SidebarsConfig = {
   docsSidebar: [
     {
       type: "category",
@@ -153,4 +151,4 @@ const sidebars = {
   ],
 };
 
-module.exports = sidebars;
+export default sidebars;
diff --git a/packages/website/themes/prism/atom-one-light.js b/packages/website/themes/prism/atom-one-light.js
diff --git a/packages/website/tsconfig.json b/packages/website/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "@tsconfig/docusaurus/tsconfig.json",
+  "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": ".",
     "jsx": "react-jsx"

diff --git a/packages/website/versioned_docs/version-latest/extending-typespec/basics.md b/packages/website/versioned_docs/version-latest/extending-typespec/basics.md
@@ -87,7 +87,7 @@ This will create `tsconfig.json`. But we need to make a couple changes to this.
 
 Open `./src/lib.ts` and create your library definition that registers your library with the TypeSpec compiler and defines any diagnostics your library will emit. Make sure to export the library definition as `$lib`.
 
-:::warn
+:::warning
 If `$lib` is not accessible from your library package (`import {$lib} from "my-library";`) some functionality will be unavailable like validation of emitter options, linter rules, etc.
 :::
 

diff --git a/packages/website/versioned_docs/version-latest/introduction/reproducibility.md b/packages/website/versioned_docs/version-latest/introduction/reproducibility.md
@@ -22,7 +22,7 @@ The command `npm ci` can also be used in the CI to ensure that the `package.json
 
 TypeSpec provides a library `@typespec/versioning` that can be used to describe changes to a service or library over time. Using this will ensure that a service can evolve while keeping track of the changes and allowing emitters to see the service representation at different versions.
 
-[See versioning docs](../standard-library/versioning/reference/index.md)
+[See versioning docs](../standard-library/versioning/reference/index.mdx)
 
 ## 3. Change to the TypeSpec spec
 
@@ -32,5 +32,5 @@ Using version control and pinning to a specific commit SHA will ensure that the
 ## Summary
 
 1. Use `package-lock.json`
-2. Use [versioning library](../standard-library/versioning/reference/index.md)
+2. Use [versioning library](../standard-library/versioning/reference/index.mdx)
 3. Keep track of commit IDs
diff --git a/.../standard-library/http/reference/index.md → ...standard-library/http/reference/index.mdx b/.../standard-library/http/reference/index.md → ...standard-library/http/reference/index.mdx
diff --git a/...rd-library/json-schema/reference/index.md → ...d-library/json-schema/reference/index.mdx b/...rd-library/json-schema/reference/index.md → ...d-library/json-schema/reference/index.mdx
diff --git a/...andard-library/openapi/reference/index.md → ...ndard-library/openapi/reference/index.mdx b/...andard-library/openapi/reference/index.md → ...ndard-library/openapi/reference/index.mdx
diff --git a/...ndard-library/openapi3/reference/index.md → ...dard-library/openapi3/reference/index.mdx b/...ndard-library/openapi3/reference/index.md → ...dard-library/openapi3/reference/index.mdx
diff --git a/...ndard-library/protobuf/reference/index.md → ...dard-library/protobuf/reference/index.mdx b/...ndard-library/protobuf/reference/index.md → ...dard-library/protobuf/reference/index.mdx
diff --git a/...tandard-library/reference/js-api/index.md → ...andard-library/reference/js-api/index.mdx b/...tandard-library/reference/js-api/index.md → ...andard-library/reference/js-api/index.mdx
diff --git a/.../standard-library/rest/reference/index.md → ...standard-library/rest/reference/index.mdx b/.../standard-library/rest/reference/index.md → ...standard-library/rest/reference/index.mdx
diff --git a/...ard-library/versioning/reference/index.md → ...rd-library/versioning/reference/index.mdx b/...ard-library/versioning/reference/index.md → ...rd-library/versioning/reference/index.mdx
-Original file line number
+Diff line change
@@ Expand Up @@
     Open `./src/lib.ts` and create your library definition that registers your library with the TypeSpec compiler and defines any diagnostics your library will emit. Make sure to export the library definition as `$lib`.
-    :::warn
+    :::warning
     If `$lib` is not accessible from your library package (`import {$lib} from "my-library";`) some functionality will be unavailable like validation of emitter options, linter rules, etc.
     :::
@@ Expand Down @@