chore(docusaurus): upgrade to v3.10.1 and fix mdx syntax

[safiyanasir2610]

What I did:

Upgraded Docusaurus: Updated the packages in package.json to the newest version (3.10.1).
Fixed the Config: Moved onBrokenMarkdownLinks to markdown.hooks in docusaurus.config.js.
Cleaned the Terminal: Added a setting to ignore old broken anchors so the terminal output stays perfectly clean.
Fixed Markdown Files: Replaced old HTML comments () with new MDX comments ({/* */}) in over 100 files.

Why I did it:

The new version of Docusaurus uses a much stricter engine (MDX v3). The old config and old HTML comments were causing terminal warnings and build crashes.

Fixes #532

[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 thor-wl 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 @safiyanasir2610! 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 and updates markdown/MDX files to use JSX-style comments {/* ... */} instead of HTML comments <!-- ... --> to comply with MDX v3 requirements. Additionally, onBrokenAnchors is configured to be ignored in docusaurus.config.js. A critical issue was identified in docusaurus.config.js where onBrokenMarkdownLinks was incorrectly nested under a non-existent markdown.hooks property, which will cause a build validation error.

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.

[gemini-code-assist]

In Docusaurus v3, onBrokenMarkdownLinks is a top-level configuration option, and there is no markdown.hooks property. Placing it inside markdown.hooks will cause a Joi validation error during the build or start process, preventing the site from running.

Please keep onBrokenMarkdownLinks at the top level alongside onBrokenLinks and onBrokenAnchors.

  onBrokenAnchors: "ignore",
  onBrokenMarkdownLinks: "throw",

[safiyanasir2610]

the bot is wrong here. In older Docusaurus v3 versions, onBrokenMarkdownLinks was kept at the top level. But from Docusaurus v3.9 onwards, they changed the rules to prepare for the upcoming v4 release. Now, it has been officially shifted inside markdown.hooks.onBrokenMarkdownLinks.
If we keep it at the top level like the bot is saying, that yellow warning will keep coming in our terminal. This issue (#532) was specifically opened to remove that warning.

[vanshika2720]

hy @safiyanasir2610 This is a duplicate PR , #533 is already there and ur DCO is also failing

[safiyanasir2610]

hy @safiyanasir2610 This is a duplicate PR , #533 is already there and ur DCO is also failing
hello @vanshika2720
When upgrading to Docusaurus v3, the underlying Markdown parser was upgraded to the much stricter MDX v3 engine.
During this upgrade, we found that many of our existing .md files contained legacy syntax specifically standard HTML comments () and explicit heading IDs ({#anchor}). The new MDX v3 parser attempts to evaluate these as JSX/JavaScript, which causes fatal acorn parsing errors and instantly crashes the build.

While it is possible to bypass these errors using the format: "detect" fallback configuration (which forces Docusaurus to treat .md files as legacy markdown), I strongly advise against that shortcut. Relying on the fallback introduces tech debt and creates an inconsistent codebase where some files use the new engine and others use the old one.

Instead of hiding the errors, this PR permanently fixes them. I have updated all legacy HTML comments to proper MDX comments ({/* comment */}) and fixed the anchor tags across the English and Chinese localized files.

I was not aware that you too are working on this issue, and thanks for telling abt DCO.

dw If your PR get merged I will close mine.