Skip to content

docs: update to docusaurus 3.10 #19522

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
317brian merged 6 commits into from
Jun 23, 2026
Merged

docs: update to docusaurus 3.10 #19522

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
035b70a
docs: update to docusaurus 3.10
317brian May 26, 2026
9c7ad9c
update readme
317brian Jun 2, 2026
86538bd
Merge branch 'master' into 310-upgrade-docusaurus
317brian Jun 4, 2026
2c19a87
update package.json and package-lock
317brian Jun 4, 2026
065db3d
Merge branch 'master' into 310-upgrade-docusaurus
317brian Jun 22, 2026
4ad4136
update deprecated config
317brian Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ See the [latest documentation](https://druid.apache.org/docs/latest/) for the do

Make documentation and tutorials updates in [`/docs`](https://github.com/apache/druid/tree/master/docs) using [Markdown](https://www.markdownguide.org/) or extended Markdown [(MDX)](https://mdxjs.com/). Then, open a pull request.

To build the site locally, you need Node 18 or higher and to install Docusaurus 3 with `npm|yarn install` in the `website` directory. Then you can run `npm|yarn start` to launch a local build of the docs.
To build the site locally, you need Node 22 or higher and to install Docusaurus 3 with `npm|yarn install` in the `website` directory. Then you can run `npm|yarn start` to launch a local dev preview of the docs.

@FrankChen021 FrankChen021 Jun 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Keep the documented Node requirement in sync with build tooling

The README now says the docs require Node 22 or higher, but the actual website metadata and automation still point at older runtimes: website/package.json allows >=18.0 and Volta pins 18.20.7, while .github/scripts/web-checks.sh installs the web-console Maven-configured Node 20.9.0 before running the docs build. If Docusaurus 3.10 now requires Node 22 for this site, contributors using Volta and the existing web checks will still run unsupported Node versions; otherwise the new README requirement is misleading. Please update the package metadata and CI/tooling Node version, or keep the README aligned with the supported runtime.


If you're looking to update non-doc pages like Use Cases, those files are in the [`druid-website-src`](https://github.com/apache/druid-website-src/tree/master) repo.

Expand Down
7 changes: 6 additions & 1 deletion website/docusaurus.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,5 +160,10 @@ module.exports={
"src": "img/favicon.png"
}
},
}
},
future: {
v4: {
fasterByDefault: true,
removeLegacyPostBuildHeadAttribute: true
}}
}
15 changes: 8 additions & 7 deletions website/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,20 +24,21 @@
"npm": "10.8.2"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "3.7.0",
"@docusaurus/types": "3.7.0",
"@docusaurus/module-type-aliases": "3.10.1",
"@docusaurus/types": "3.10.1",
"markdown-spellcheck": "^1.3.1",
"postcss": "^8.4.24",
"sass": "^1.62.1"
},
"dependencies": {
"@docusaurus/core": "^3.7.0",
"@docusaurus/plugin-client-redirects": "^3.7.0",
"@docusaurus/preset-classic": "^3.7.0",
"@docusaurus/theme-mermaid": "^3.7.0",
"@docusaurus/core": "^3.10.1",

@FrankChen021 FrankChen021 Jun 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Regenerate the website lockfile with the Docusaurus upgrade

This PR updates the website dependencies to Docusaurus 3.10.1 and adds new packages, but website/package-lock.json is unchanged: its root entry still declares the old ^3.7.0 Docusaurus ranges and the resolved graph still pins 3.7.0 while missing the new direct dependency entries. A clean reproducible install such as npm ci will reject the mismatch, and lockfile-based consumers will not be testing the dependency graph this PR intends to ship. Please regenerate and commit website/package-lock.json with the same package manager used for the website.

"@docusaurus/plugin-client-redirects": "^3.10.1",
"@docusaurus/preset-classic": "^3.10.1",
"@docusaurus/theme-mermaid": "^3.10.1",
"@docusaurus/faster": "^3.10.1",

@FrankChen021 FrankChen021 Jun 2, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Regenerate the tracked website lockfile

The PR updates Docusaurus to 3.10.1 and adds @docusaurus/faster plus @mermaid-js/layout-elk, but website/package-lock.json is still tracked with the old 3.7.0 graph and docusaurus@1.14.7. A clean npm ci will reject the out-of-sync manifest/lockfile, and lockfile-based installs will not get the intended dependency graph. Regenerate and commit website/package-lock.json with the repo's npm version.

"clsx": "^1.1.1",
"docusaurus": "^1.14.7",
"docusaurus-lunr-search": "^3.6.0",

@FrankChen021 FrankChen021 Jun 2, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Rewrite legacy Docusaurus scripts after removing v1

The removed docusaurus@1.14.7 package is the provider for legacy binaries like docusaurus-examples, docusaurus-publish, docusaurus-version, docusaurus-rename-version, and docusaurus-write-translations, while the remaining Docusaurus package exposes the docusaurus CLI. After a clean install with the regenerated lockfile, the existing scripts at the top of package.json will fail with command-not-found unless they are converted to Docusaurus 3 CLI forms or removed.

"@mermaid-js/layout-elk": "^0.1.9",
"fast-glob": "^3.2.2",
"fs-extra": "^8.1.0",
"react": "^18.2.0",
Expand Down
Loading