Upgrade Docusaurus 2.0.0-beta.5 → 3.10.2

.github/workflows/documentation.yml

@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
         with:
-          node-version: '14.x'
+          node-version: '20.x'
       - name: Test Build
         run: |
           cd docs
@@ -33,7 +33,7 @@ jobs:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
         with:
-          node-version: '14.x'
+          node-version: '20.x'
       - uses: webfactory/ssh-agent@v0.5.0
         with:
           ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}

docs/docusaurus.config.js

@@ -14,10 +14,21 @@ module.exports = {
   url: 'https://mapillary.github.io',
   baseUrl: '/mapillary-python-sdk/',
   onBrokenLinks: 'warn',
-  onBrokenMarkdownLinks: 'warn',
   favicon: 'img/favicon.ico',
   organizationName: 'mapillary', // Usually your GitHub org/user name.
   projectName: 'mapillary-python-sdk', // Usually your repo name.
+  markdown: {
+    // Parse .md as CommonMark and reserve MDX for .mdx. The API docs under
+    // docs/ are generated from Python docstrings by scripts/documentation.py
+    // and contain literal braces (e.g. "{ id: string, url: string }") that
+    // MDX would try to evaluate as JSX expressions. Escaping them in the
+    // generated output would only break again on the next docs-gen run.
+    format: 'detect',
+    // Was siteConfig.onBrokenMarkdownLinks, deprecated in v3 and removed in v4
+    hooks: {
+      onBrokenMarkdownLinks: 'warn',
+    },
+  },
   themeConfig: {
     navbar: {
       title: 'Mapillary Python SDK',
@@ -139,6 +150,29 @@ module.exports = {
       copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc. Built with Docusaurus.`,
     },
   },
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        // Docusaurus treats a doc whose filename matches its folder as that
+        // category's index page, a convention introduced after 2.0.0-beta.5.
+        // Upgrading therefore shortened these seven URLs. Redirect the old
+        // paths so external links and bookmarks keep working.
+        redirects: [
+          'mapillary',
+          'mapillary.config',
+          'mapillary.config.api',
+          'mapillary.controller',
+          'mapillary.models',
+          'mapillary.models.api',
+          'mapillary.utils',
+        ].map((name) => ({
+          from: `/docs/${name}/${name}`,
+          to: `/docs/${name}`,
+        })),
+      },
+    ],
+  ],
   presets: [
     [
       '@docusaurus/preset-classic',

docs/package.json

@@ -18,16 +18,14 @@
     "prettier:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,md,mdx}\""
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.5",
-    "@docusaurus/preset-classic": "2.0.0-beta.5",
-    "@mdx-js/react": "^1.6.21",
-    "@svgr/webpack": "^5.5.0",
-    "clsx": "^1.1.1",
-    "file-loader": "^6.2.0",
-    "react": "^17.0.1",
-    "react-dom": "^17.0.1",
-    "url-loader": "^4.1.1",
-    "yarn": "^1.22.15"
+    "@docusaurus/core": "^3.10.2",
+    "@docusaurus/plugin-client-redirects": "^3.10.2",
+    "@docusaurus/preset-classic": "^3.10.2",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.1.1",
+    "prism-react-renderer": "^2.4.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   },
   "devDependencies": {
     "@babel/eslint-parser": "^7.13.10",
@@ -53,5 +51,8 @@
       "last 1 firefox version",
       "last 1 safari version"
     ]
+  },
+  "engines": {
+    "node": ">=20.0"
   }
 }