feat: docusaurus 3 (#196)

# Description

Docusaurus recently released `v3.0.0` (now `v3.0.1` with patch fixes).
The typedoc generator plugin was causing issues as `.md` is now
processed as `MDX`.

# Changes

- [x] Bump dependencies to docusaurus `v3.0.1`
- [x] Migrate all config files to typescript

## Related Issues

Fixes #77

docs/cow-protocol/tutorials/cow-swap/swap.mdx

@@ -39,7 +39,7 @@ This has the benefits of:
 - Not having to re-approve every time you trade
 - Saving on gas costs
 
-<TokenApprovalWarning token="WETH" spender="GPv2VaultRelayer" />
+<TokenApprovalWarning spender="GPv2VaultRelayer" />
 
 Once the `approve` transaction is confirmed, you can proceed to swap!
 

docs/cow-protocol/tutorials/cow-swap/twap.mdx

@@ -74,7 +74,7 @@ If your wallet is unsupported, upgrade to a Safe with the special fallback handl
 
 Check all the details of your order, including price protection and limit price. Once you approve the details, sign the transaction in your Safe interface.
 
-<TokenApprovalWarning token="YourToken" spender="TWAPContract" />
+<TokenApprovalWarning spender="TWAPContract" />
 
 Be careful when signing an intent to trade. All of the associated parameters are final and cannot be changed once the intent is signed and submitted to the API. If you make a mistake, you will need to cancel the intent and create a new one. You can do this in the orders overview.
 

docusaurus.config.js → docusaurus.config.ts

@@ -1,11 +1,9 @@
-// @ts-check
-// Note: type annotations allow type checking and IDEs autocompletion
+import {themes as prismThemes} from 'prism-react-renderer';
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
 
-const lightCodeTheme = require('prism-react-renderer/themes/github');
-const darkCodeTheme = require('prism-react-renderer/themes/dracula');
-
-const math = require('remark-math');
-const katex = require('rehype-katex');
+import remarkMath from 'remark-math';
+import rehypeKatex from 'rehype-katex';
 
 // if you are using dotenv, you can load the env vars here
 require('dotenv').config();
@@ -14,8 +12,7 @@ const url = process.env.URL ?? 'http://localhost:3000';
 const baseUrl = process.env.BASE_URL ?? '/';
 const trailingSlash = process.env.TRAILING_SLASH ? process.env.TRAILING_SLASH === "true" : false;
 
-/** @type {import('@docusaurus/types').Config} */
-const config = {
+const config: Config = {
   title: 'CoW Protocol Documentation',
   tagline: 'Tagline here',
   favicon: 'img/favicon.png',
@@ -45,15 +42,15 @@ const config = {
   },
 
   markdown: {
+    format: "detect",
     mermaid: true,
   },
   themes: ['@docusaurus/theme-mermaid', '@docusaurus/theme-live-codeblock', "docusaurus-json-schema-plugin"],
 
   presets: [
     [
       'classic',
-      /** @type {import('@docusaurus/preset-classic').Options} */
-      ({
+      {
         docs: {
           routeBasePath: '/',
           sidebarPath: require.resolve('./sidebars.js'),
@@ -81,10 +78,10 @@ const config = {
                     return noReadmeSidebar;
                   },
           remarkPlugins: [
-            math,
+            remarkMath,
             [require('@docusaurus/remark-plugin-npm2yarn'), { sync: true, converters: ['yarn', 'pnpm'] }],
           ],
-          rehypePlugins: [katex],
+          rehypePlugins: [rehypeKatex],
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
           editUrl:
@@ -93,7 +90,7 @@ const config = {
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
         },
-      }),
+      } satisfies Preset.Options,
     ],
   ],
 
@@ -152,8 +149,7 @@ const config = {
   ],
 
   themeConfig:
-    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
-    ({
+    {
       // Replace with your project's social card
       image: 'img/og-meta-cowprotocol.png',
       navbar: {
@@ -234,16 +230,21 @@ const config = {
         copyright: `Copyright © ${new Date().getFullYear()} CoW Protocol`,
       },
       prism: {
-        theme: lightCodeTheme,
-        darkTheme: darkCodeTheme,
+        theme: prismThemes.github,
+        darkTheme: prismThemes.dracula,
         additionalLanguages: ['solidity', 'json'],
       },
       colorMode: {
         defaultMode: 'light',
         disableSwitch: false,
         respectPrefersColorScheme: true,
       },
-    }),
+      algolia: {
+        appId: 'VTLPKRZC26',
+        apiKey: '5b23e6db64cdeeac6da5569f69d77149',
+        indexName: 'betacow',
+      }
+    } satisfies Preset.ThemeConfig,
 };
 
 module.exports = config;

package.json

@@ -21,32 +21,34 @@
     "fmt": "prettier --write \"**/*.md\""
   },
   "dependencies": {
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/plugin-ideal-image": "^2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
-    "@docusaurus/remark-plugin-npm2yarn": "2.4.3",
-    "@docusaurus/theme-live-codeblock": "2.4.3",
-    "@docusaurus/theme-mermaid": "2.4.3",
-    "@mdx-js/react": "^1.6.22",
-    "clsx": "^1.2.1",
+    "@docusaurus/core": "^3.0.1",
+    "@docusaurus/plugin-ideal-image": "^3.0.1",
+    "@docusaurus/preset-classic": "^3.0.1",
+    "@docusaurus/remark-plugin-npm2yarn": "^3.0.1",
+    "@docusaurus/theme-live-codeblock": "^3.0.1",
+    "@docusaurus/theme-mermaid": "^3.0.1",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
     "docusaurus-json-schema-plugin": "^1.7.0",
     "hast-util-is-element": "1.1.0",
-    "prism-react-renderer": "^1.3.5",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2",
-    "rehype-katex": "5",
-    "remark-math": "3",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "rehype-katex": "7",
+    "remark-math": "6",
     "swagger-ui-react": "4.15.5"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.4.3",
-    "@tsconfig/docusaurus": "^1.0.5",
+    "@docusaurus/module-type-aliases": "3.0.1",
+    "@docusaurus/tsconfig": "3.0.1",
+    "@docusaurus/types": "3.0.1",
+    "@types/react": "^18.0.0",
     "docusaurus-plugin-typedoc": "^0.21.0",
     "dotenv": "^16.3.1",
     "prettier": "^3.0.3",
     "typedoc": "^0.25.3",
     "typedoc-plugin-markdown": "^3.17.0",
-    "typescript": "^4.9.5"
+    "typescript": "~5.2.2"
   },
   "resolutions": {
     "types-ramda": "0.29.4"

sidebars.js → sidebars.ts

@@ -1,3 +1,5 @@
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+
 /**
  * Creating a sidebar enables you to:
  - create an ordered group of docs
@@ -11,8 +13,7 @@
 
 // @ts-check
 
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
-const sidebars = {
+const sidebars: SidebarsConfig = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
   // tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
 

tsconfig.json

@@ -1,11 +1,11 @@
 {
   // This file is not used in compilation. It is here just for a nice editor experience.
-  "extends": "@tsconfig/docusaurus/tsconfig.json",
+  "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": ".",
     "resolveJsonModule": true,
     // Extend '@tsconfig/docusaurs/tsconfig.json'.types with 'docusaurus-json-schema-plugin'
-    "types": ["node", "@docusaurus/module-type-aliases", "@docusaurus/theme-class", "docusaurus-json-schema-plugin"],
+    "types": ["node", "@docusaurus/module-type-aliases", "@docusaurus/theme-classic", "docusaurus-json-schema-plugin"],
     "esModuleInterop": true
   }
 }