Upgrade Docusaurus 2.0.0-beta.5 → 3.10.2 (#186)

* Upgrade Docusaurus 2.0.0-beta.5 -> 3.10.2

The docs site was pinned to a 2021 Docusaurus beta, which held the entire
JS dependency tree in place and made most of the docs/yarn.lock security
advisories unfixable individually. Dependabot had been reporting
security_update_not_possible for exactly this reason, e.g.
decode-uri-component could not move past 0.2.0 because
@docusaurus/core@2.0.0-beta.5 required it transitively.

Changes:
- @docusaurus/core and preset-classic 2.0.0-beta.5 -> ^3.10.2
- react/react-dom ^17 -> ^18.3.1, @mdx-js/react ^1 -> ^3 (v3 peer deps)
- clsx ^1 -> ^2, prism-react-renderer added (required by v3 preset)
- dropped @svgr/webpack, file-loader, url-loader and the stray 'yarn'
  dependency: all unused here, every svg import in src/ is commented out
- engines.node >=20.0, matching Docusaurus 3's own requirement
- CI node-version 14.x -> 20.x in documentation.yml (14 is EOL, and
  Docusaurus 3 will not run on it)

Two config migrations were needed:

markdown.format: 'detect' - MDX v3 is stricter than v1 and tried to
evaluate literal braces in the generated API docs as JSX expressions,
failing on "{ id: string, url: string }" in mapillary.interface.md.
'detect' parses .md as CommonMark and reserves MDX for .mdx. Escaping the
braces instead would have been undone by the next scripts/documentation.py
run, since those files are generated from Python docstrings.

onBrokenMarkdownLinks moved under markdown.hooks, where v3 expects it;
the top-level option is deprecated and removed in v4.

Verified locally on Node 20: build succeeds, 43 HTML pages generated, and
the page that previously failed to compile now renders its braces as
literal text.

Notable transitive results: webpack 5.74.0 -> 5.110.3 (the bump #175
attempted and could not land, since 5.110.3 is incompatible with the
beta), websocket-driver 0.7.4 -> 0.7.5, svgo 1.3.2 -> 3.3.5, browserslist
4.14.2 -> 4.28.9, shell-quote 1.7.2 -> 1.10.0, postcss 8.4.16 -> 8.5.28,
and axios, ua-parser-js and decode-uri-component dropped entirely.

* Add client redirects for the seven doc URLs the upgrade moves

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 shortens seven API doc URLs, e.g.

    /docs/mapillary.config/mapillary.config -> /docs/mapillary.config

Nothing in the repo references the old paths and every internal link
regenerates, but external bookmarks and inbound links would 404. This
adds @docusaurus/plugin-client-redirects and maps each old path to its
new one.

Verified by building and following each redirect: all seven stubs are
emitted with the correct target, and the content reached through them
matches what the old URL served. The only differences are chrome the
v3 theme renders differently (prev/next arrows, dark-mode toggle icons).

Build output goes 43 -> 50 pages: 43 real pages plus 7 redirect stubs.
Internal link check still reports 0 unresolvable across 49 links.

docs/tags is intentionally not redirected. It existed in v2 as an empty
tag index with no tags to list; v3 omits it rather than emitting an
empty page.

Author: caglarpir

.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"
   }
 }