Upgrade Docusaurus 2.0.0-beta.5 → 3.10.2 - #186
Conversation
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 mapillary#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.
meta-cla
Bot
added
the
CLA Signed
|
Followed up with a differential comparison of the two built sites, since "the build succeeds" says nothing about whether the site still renders. Built Two things came out of it that were not in the original description. 1. Seven doc URLs change — please read before mergingDocusaurus applies a category index convention: a doc whose filename matches its folder becomes that category’s index page. That convention postdates beta.5, so the upgrade activates it. Assessment:
If you would rather preserve the old paths, Also gained: 2. The upgrade fixes a pre-existing rendering bugEvery shared page’s text changed, which looked alarming until I checked the cause. The generated API docs were displaying raw markdown asterisks to readers:
Parameter names and types were rendering as literal Verified no page lost more than 15% of its vocabulary; the only words dropped sitewide are chrome ( Full results |
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.
|
Added What was addedThe plugin plus a mapping for each path the category-index convention shortens: 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}` })),Verified, not assumedEvery redirect stub is emitted with the right target: I then followed each redirect and compared the content it lands on against what the old URL used to serve. All seven resolve to equivalent content. The only words that differ are theme chrome the v3 renders differently — the Re-ran the full differential check afterwards: One deliberate omission
|
1 participant
The docs site was pinned to a 2021 Docusaurus beta. That single pin held the whole JS dependency tree in place and is the root cause behind most of the ~145 open
docs/yarn.lockadvisories — Dependabot has been reportingsecurity_update_not_possiblefor exactly this, e.g.decode-uri-componentcould not move past 0.2.0 because@docusaurus/core@2.0.0-beta.5required it transitively.It is also why #175 could not land: webpack 5.110.3 is incompatible with the beta. I isolated that before closing #175 — Node 20 alone builds fine, Node 20 + webpack 5.110.3 fails with
ValidationError: Progress Plugin has been initialized using an options object that does not match the API schema. This PR gets webpack to 5.110.3 as a side effect, because v3 is compatible with it.Changes
@docusaurus/core+preset-classic2.0.0-beta.5→^3.10.2react/react-dom^17→^18.3.1,@mdx-js/react^1→^3(v3 peer requirements)clsx^1→^2, addedprism-react-renderer(required by the v3 preset)@svgr/webpack,file-loader,url-loader, and a strayyarndependency — all unused here; every svg import insrc/is commented outengines.node: ">=20.0", matching Docusaurus 3node-version14.x→20.xindocumentation.yml(14 is EOL, and v3 will not run on it)Two config migrations
markdown.format: 'detect'— MDX v3 is far stricter than v1 and tried to evaluate literal braces in the generated API docs as JSX:Line 376 is
22. mesh - { id: string, url: string } - URL to the mesh, straight out of a Python docstring.'detect'parses.mdas CommonMark and reserves MDX for.mdx. Escaping the braces instead would be undone by the nextscripts/documentation.pyrun, since those files are generated.onBrokenMarkdownLinksmoved undermarkdown.hooks, where v3 expects it. The top-level option is deprecated and removed in v4.Verified locally on Node 20
yarn buildsucceeds, 43 HTML pages generated, no errors and no deprecation warnings{ id: string, url: string }as literal text — confirmed in the built HTML rather than assumedSecurity impact
Known remainder
postcss@7.0.39survives, pulled in by the oldstylelint@13devDependency (via@stylelint/postcss-markdown/postcss-css-in-js). Clearing it means upgrading stylelint 13 → 16, which needs a config migration in.stylelintrc.js. The same applies toeslint@7. Those tools are not run by any workflow — onlynpm run buildis — so I left them out to keep this reviewable. Worth a follow-up.The two remaining build warnings (inline blog authors, missing truncation markers) are about the leftover Docusaurus sample blog posts and predate this change.
Test plan
CI
checksjob is the real test — it runsyarn install --frozen-lockfile && npm run buildon the new lockfile and Node 20.