chore(docusaurus): upgrade to v3.10.1 and migrate markdown hooks

[vanshika2720]

• Please check if the PR fulfills these requirements

• The commit message follows our guidelines

What kind of change does this PR introduce?

/kind cleanup

---

What this PR does / why we need it

This PR upgrades the website's Docusaurus dependencies from v3.9.2 to v3.10.1 and migrates the deprecated markdown link hook configuration to its new location.

These changes remove deprecation warnings from the build output, keep the project aligned with current Docusaurus recommendations, and improve compatibility with future Docusaurus v4 upgrades.

---

Changes

Dependency Upgrades

Upgraded the following packages to v3.10.1:

• @docusaurus/core
• @docusaurus/preset-classic
• @docusaurus/module-type-aliases
• @docusaurus/types

Additionally:

• Added @docusaurus/[email protected] to align with the existing future.v4: true configuration.

Configuration Migration

Migrated the deprecated top-level configuration:

onBrokenMarkdownLinks: "throw",

to the new Docusaurus-supported structure:

markdown: {
  format: "detect",
  hooks: {
    onBrokenMarkdownLinks: "throw",
  },
},

The markdown.format: "detect" option allows standard .md files to be parsed using CommonMark while preserving MDX support where needed, preventing MDX v3 parsing issues on regular markdown content.

---

Verification

Installation

• npm install completed successfully
• Lockfile updated correctly
• No dependency conflicts encountered

Build Validation

• npm run build
• npm run build -- --locale en
• npm run build -- --locale zh-Hans

Configuration Validation

• No deprecated onBrokenMarkdownLinks warnings during build
• No remaining top-level onBrokenMarkdownLinks configuration entries
• Multi-locale builds complete successfully

---

Which issue(s) does this PR fix?

#532

Fixes deprecated Docusaurus configuration warnings and prepares the documentation site for improved Docusaurus v4 compatibility.

[volcano-sh-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign william-wang for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[volcano-sh-bot]

Welcome @vanshika2720! It looks like this is your first PR to volcano-sh/website 🎉

[gemini-code-assist]

Code Review

This pull request upgrades Docusaurus dependencies to version 3.10.1, adds the @docusaurus/faster package, and configures markdown format detection. However, nesting onBrokenMarkdownLinks under markdown.hooks is incorrect as it is a top-level configuration option in Docusaurus, which would cause the setting to be ignored.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[vanshika2720]

Just adding a bit of context on a few implementation details:

• markdown.format: "detect" was required for the upgrade because the repository already uses future.v4: true. Without it, several existing .md blog posts containing HTML comments (<!-- -->) failed MDX compilation during the build. Using "detect" preserves the current behavior by parsing .md files as CommonMark and .mdx files as MDX.

• I initially tested with @docusaurus/faster, but to keep the scope focused on the version upgrade and deprecation migration, the final approach was to explicitly set future.faster: false, preserving the existing build pipeline without introducing an additional dependency.

• The large package-lock.json diff is due to the Docusaurus upgrade and regeneration of its transitive dependencies. No unrelated source changes were included; the functional changes are limited to package.json, package-lock.json, and docusaurus.config.js.

Build and locale checks completed successfully, and the deprecated onBrokenMarkdownLinks warning is no longer emitted.

[hajnalmt]

Thanks for the PR,
I am somewhat not understanding the description and the faster handling. I don't see docosaurus@faster in the dependency directly, you added it as a peerDependency, why to add the flag with false then? Shouldn't we add it with the correct version with the upgrade? Also * can break things for other people (if they switch the flag to true), because @docusaurus/faster is tightly coupled to core internals, eg.: a 3.9.x faster against a 3.10.1 core can break or behave oddly. You want it to match core exactly (3.10.1).

Otherwise I am okay with the PR 👍 Thank you!

[hajnalmt]

Is there an actual reason to set this if we don't enable it?

[vanshika2720]

@hajnalmt I tested removing it after your comment to verify whether it was still needed. The build fails without it because this repository already has future.v4: true, and in Docusaurus 3.10.x that enables the faster pipeline by default. Since this project doesn't include @docusaurus/faster as a dependency, the build errors unless future.faster is explicitly set to false.

So I kept the flag to preserve the current build behavior and added a short comment in the config explaining why it's there. This keeps the upgrade focused on the Docusaurus version bump without enabling the faster pipeline.

[hajnalmt]

Agh thanks for the clarification, I understand now.

[hajnalmt]

Are we sure in this? Asterisk means any version here right?

[vanshika2720]

@hajnalmt The @docusaurus/faster: "*" entry in package-lock.json isn't something this PR adds or controls. It's inherited from @docusaurus/core's own package.json, where it's declared as an optional peer dependency.

Since it's generated by npm during lockfile regeneration, we can't pin or modify it in package-lock.json. If we decide to enable the faster pipeline in the future, we'd add @docusaurus/faster explicitly to package.json with the matching version (e.g. 3.10.1) so it stays aligned with the Docusaurus core version.

[hajnalmt]

I see thanks! It's alright this way then.

[vanshika2720]

@hajnalmt @JesseStutler please review

[hajnalmt]

/lgtm

Thanks!

[hajnalmt]

Agh thanks for the clarification, I understand now.