build: upgrade to Docusaurus 3 (#563)

Co-authored-by: David Sanders <[email protected]>

docusaurusConfig.ts → docusaurus.config.ts

@@ -1,6 +1,7 @@
 import path from 'path';
 import { Config } from '@docusaurus/types';
 import npm2yarn from '@docusaurus/remark-plugin-npm2yarn';
+import { themes as prismThemes } from 'prism-react-renderer';
 
 import apiLabels from './src/transformers/api-labels';
 import apiOptionsClass from './src/transformers/api-options-class';
@@ -33,8 +34,9 @@ const config: Config = {
       respectPrefersColorScheme: true,
     },
     prism: {
-      theme: require('prism-react-renderer/themes/github'),
-      darkTheme: require('prism-react-renderer/themes/dracula'),
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+      additionalLanguages: ['diff', 'json'],
     },
     tableOfContents: {
       minHeadingLevel: 2,
@@ -194,10 +196,10 @@ const config: Config = {
   },
   plugins: [
     'docusaurus-plugin-sass',
-    path.resolve(__dirname, './src/plugins/apps'),
-    path.resolve(__dirname, './src/plugins/releases'),
-    path.resolve(__dirname, './src/plugins/fiddle'),
-    path.resolve(__dirname, './src/plugins/governance'),
+    path.resolve(__dirname, './src/plugins/apps/index.ts'),
+    path.resolve(__dirname, './src/plugins/releases/index.ts'),
+    path.resolve(__dirname, './src/plugins/fiddle/index.ts'),
+    path.resolve(__dirname, './src/plugins/governance/index.ts'),
   ],
   presets: [
     [

package.json

@@ -30,65 +30,43 @@
     "prepare": "husky install"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.4.3",
-    "@docusaurus/plugin-google-analytics": "^2.4.3",
-    "@docusaurus/preset-classic": "^2.4.3",
-    "@docusaurus/remark-plugin-npm2yarn": "^2.4.3",
-    "@docusaurus/theme-mermaid": "^2.4.3",
-    "@mdx-js/react": "^1.6.21",
-    "@types/react": "^17.0.1",
+    "@docusaurus/core": "3.3.2",
+    "@docusaurus/plugin-google-analytics": "3.3.2",
+    "@docusaurus/preset-classic": "3.3.2",
+    "@docusaurus/remark-plugin-npm2yarn": "3.3.2",
+    "@docusaurus/theme-mermaid": "3.3.2",
+    "@mdx-js/react": "^3.0.0",
     "clsx": "^1.1.1",
     "docusaurus-plugin-sass": "^0.2.1",
     "dotenv": "^16.0.3",
     "execa": "^5.0.0",
     "node-fetch": "^2.6.7",
-    "react": "^17.0.1",
-    "react-dom": "^17.0.1",
-    "react-markdown": "^6.0.3",
+    "prism-react-renderer": "^2.3.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-markdown": "^9.0.1",
     "react-useportal": "^1.0.14",
     "sass": "^1.37.5"
   },
-  "browserslist": {
-    "production": [
-      ">0.5%",
-      "not dead",
-      "not op_mini all"
-    ],
-    "development": [
-      "last 1 chrome version",
-      "last 1 firefox version",
-      "last 1 safari version"
-    ]
-  },
-  "lint-staged": {
-    "*.{html,json,md,yml}": "prettier --write",
-    "*.{js,jsx,ts,tsx}": [
-      "prettier --write",
-      "eslint --fix"
-    ]
-  },
-  "husky": {
-    "hooks": {
-      "pre-commit": "lint-staged"
-    }
-  },
   "devDependencies": {
     "@actions/core": "^1.2.7",
     "@actions/github": "^4.0.0",
     "@crowdin/cli": "^3.9.3",
     "@crowdin/crowdin-api-client": "^1.21.1",
-    "@docusaurus/module-type-aliases": "^2.4.3",
-    "@docusaurus/tsconfig": "^3.3.2",
-    "@docusaurus/types": "^2.4.3",
+    "@docusaurus/module-type-aliases": "3.3.2",
+    "@docusaurus/tsconfig": "3.3.2",
+    "@docusaurus/types": "3.3.2",
     "@electron/docs-parser": "^1.0.1",
     "@electron/lint-roller": "^1.11.1",
+    "@tsconfig/docusaurus": "^2.0.3",
     "@types/fs-extra": "^9.0.13",
-    "@types/mdast": "^3.0.10",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^18.11.10",
     "@types/node-fetch": "^2.6.2",
+    "@types/react": "^18.3.1",
     "@types/semver": "^7.3.13",
     "@types/tar-stream": "^2.2.2",
-    "@types/unist": "^2.0.3",
+    "@types/unist": "^3.0.2",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "@typescript-eslint/parser": "^6.21.0",
     "del": "^6.0.0",
@@ -107,17 +85,37 @@
     "latest-version": "^5.1.0",
     "lint-staged": "^13.2.0",
     "make-dir": "^3.1.0",
+    "mdast-util-frontmatter": "^2.0.1",
     "mdast-util-to-string": "^2.0.0",
     "prettier": "^2.8.0",
-    "remark": "^13.0.0",
-    "remark-gfm": "^1.0.0",
+    "remark": "^15.0.0",
+    "remark-gfm": "^4.0.0",
     "tar-stream": "^2.2.0",
-    "ts-node": "^10.9.1",
     "typescript": "5.3.2",
-    "unist-util-visit-parents": "^3.1.1"
+    "unist-util-visit-parents": "^6.0.1"
   },
-  "resolutions": {
-    "**/latest-version/package-json": "7.0.0",
-    "**/@mdx-js/mdx/remark-parse/trim": "0.0.3"
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  },
+  "lint-staged": {
+    "*.{html,json,md,yml}": "prettier --write",
+    "*.{js,jsx,ts,tsx}": [
+      "prettier --write",
+      "eslint --fix"
+    ]
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
   }
 }

scripts/prepare-i18n-content.ts

@@ -9,7 +9,7 @@ import logger from '@docusaurus/logger';
 
 import { addFrontmatterToAllDocs } from './tasks/add-frontmatter';
 import { fixContent } from './tasks/md-fixers';
-import config from '../docusaurusConfig';
+import config from '../docusaurus.config';
 
 const DOCS_FOLDER = path.join('docs', 'latest');
 

scripts/tasks/md-fixers.ts

@@ -6,44 +6,6 @@ import globby from 'globby';
 
 import logger from '@docusaurus/logger';
 
-/**
- * RegExp used to match the details of the arguments of a function
- * in the documentation and used in `apiTransformer`. It matches:
- * >   * `userInfo` Record<String, unknown>
- * ➡ ["  * ", "`userInfo` Record<String, unknown>", "userInfo", "Record<String, unknown>", ""]
- * > * `channel` String
- * ➡ ["* ", "`channel` String", "channel", "String", ""]
- * > * `deliverImmediately` Boolean (optional) - `true` to post notifications immediately even when the subscribing app is inactive.
- * ➡ ["* ", "...", "deliverImmediately", "Boolean (optional) ", "-"] ⚠ Note the trailing space in [3]
- */
-const argumentRegex = /(\s*\*\s+)`([a-zA-Z]+?)`\s([\s\S]+?)($|\s-)/;
-
-/**
- * MDX has some problems with strings like `Promise<void>` when they
- * are out of code blocks.
- * This happens when declaring the types of the arguments. This method
- * replaces the closing `>` with the unicode character `&#62;` to
- * prevent this issue.
- * @param line
- */
-const apiTransformer = (line: string) => {
-  const matches = argumentRegex.exec(line);
-
-  if (!matches) {
-    return line;
-  }
-
-  const newLine = line.replace(
-    matches[0],
-    `${matches[1]}\`${matches[2].trim()}\` ${matches[3]
-      .trim()
-      .replace(/>/g, '&#62;')
-      .replace(/\\?</g, '&#60;')} ${matches[4].trim()}`.trimEnd() // matches[4] could be empty and thus end up with a trailing space
-  );
-
-  return newLine;
-};
-
 /**
  * RegExp use to match the old markdown format for fiddle
  * in `fiddleTransformer`.
@@ -147,7 +109,6 @@ const transform = (doc: string) => {
   const lines = doc.split('\n');
   const newDoc = [];
   const transformers = [
-    apiTransformer,
     fiddleTransformer,
     newLineOnHTMLComment,
     newLineOnAdmonition,

scripts/update-crowdin-glossary.ts

@@ -16,7 +16,7 @@ import latestVersion from 'latest-version';
 import toString from 'mdast-util-to-string';
 import fetch from 'node-fetch';
 import remarkParse from 'remark-parse';
-import unified from 'unified';
+import { unified } from 'unified';
 
 import { convertToCSV } from './utils/csv';
 import { Parent, Text } from 'mdast';

src/plugins/apps/index.ts

@@ -20,7 +20,7 @@ export interface AppsPluginContent {
   categories: Map<string, App>;
 }
 
-module.exports = async function appsPlugin() {
+export default async function appsPlugin() {
   // TODO: actually use the electron/apps repo as a data source
   const response = await fetch(
     'https://raw.githubusercontent.com/erickzhao/apps/master/index.json'
@@ -100,4 +100,4 @@ module.exports = async function appsPlugin() {
     },
   };
   return plugin;
-};
+}

src/plugins/governance/fetch-data.ts

@@ -1,5 +1,5 @@
 import got from 'got';
-import remark from 'remark';
+import { remark } from 'remark';
 import gfm from 'remark-gfm';
 import toString from 'mdast-util-to-string';
 import { Node, Parent } from 'unist';

src/theme/DocSidebarItem/Link/TagContent.tsx

@@ -7,13 +7,10 @@ import WindowsIcon from '@site/static/assets/img/platform-windows.svg';
 export default function TagContent(props: { platform: string }) {
   switch (props.platform) {
     case 'windows':
-      //@ts-expect-error "title" attribute not properly typed
       return <WindowsIcon role="img" title="Available on Windows" />;
     case 'mac':
-      //@ts-expect-error "title" attribute not properly typed
       return <MacIcon role="img" title="Available on macOS" />;
     case 'linux':
-      //@ts-expect-error "title" attribute not properly typed
       return <LinuxIcon role="img" title="Available on Linux" />;
     default:
       return <span />;

src/transformers/api-labels.ts

@@ -1,7 +1,8 @@
 import { Parent } from 'unist';
-import visitParents from 'unist-util-visit-parents';
-import { Data as HastData } from 'mdast-util-to-hast/lib/index';
-import { Emphasis, PhrasingContent, Text } from 'mdast';
+import { visitParents } from 'unist-util-visit-parents';
+import { Data as HastData } from 'hast';
+import { Emphasis } from 'mdast';
+import { isText } from '../util/mdx-utils';
 
 /**
  * This transformer adds badge styling to our raw API documentation.
@@ -63,7 +64,3 @@ function visitor(node: Emphasis) {
     }
   }
 }
-
-function isText(node: PhrasingContent): node is Text {
-  return node.type === 'text';
-}

src/transformers/api-options-class.ts

@@ -1,7 +1,8 @@
-import { Node, Parent } from 'unist';
-import { InlineCode, ListItem, Paragraph } from 'mdast';
-import { Data as HastData } from 'mdast-util-to-hast/lib/index';
-import visitParents from 'unist-util-visit-parents';
+import { Parent } from 'unist';
+import { ListItem } from 'mdast';
+import { Data as HastData } from 'hast';
+import { visitParents } from 'unist-util-visit-parents';
+import { isOptions, isParagraph } from '../util/mdx-utils';
 
 /**
  * This transformer adds the class="electron-api-options-list"
@@ -41,12 +42,3 @@ function visitor(node: ListItem) {
     node.data = hastProperties;
   }
 }
-
-function isParagraph(node: Node): node is Paragraph {
-  return node.type === 'paragraph';
-}
-
-function isOptions(node: Node): node is InlineCode {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return node.type === 'inlineCode' && (node as any).value === 'options';
-}