Sébastien Lorber

This commit implements a **configuration update** for the **Docusaurus website**, specifically disabling the `mdx1Compat.comments` feature. By modifying `docusaurus.config.ts`, the site will no longer process HTML comments within MDX files as MDX comments, thereby altering the **MDX parsing behavior**. This change ensures a more consistent interpretation of comments and prevents potential rendering issues. Consequently, the `markdown-tests-mdx.mdx` test file is refactored to remove HTML comments and align its examples with the new, disabled `mdx1Compat.comments` setting. This is a **maintenance chore** to streamline MDX processing on the website.

chore(website): Upgrade to Algolia v4.6 (#11845)

fix(core): fix `url.resolve()` Node.js deprecation warning (#11844)

This commit **upgrades the Rspack build tool to version 1.7.10** and **resolves critical compatibility issues with Yarn Plug'n'Play (PnP)**. The primary goal is to **fix build failures and ensure proper module resolution** when using Rspack in projects that utilize Yarn PnP. This **maintenance and bug fix** effort improves the stability and reliability of the build system, particularly for environments leveraging advanced dependency management. It directly impacts the **build process and developer experience** for users relying on this specific tooling combination.

This commit **fixes compatibility with TypeScript 6.0** and stabilizes the project's **Continuous Integration (CI)** pipelines. It updates numerous `tsconfig.json` files across `create-docusaurus` templates, core Docusaurus packages, and the website, primarily by adding `ignoreDeprecations: "6.0"` to manage new TypeScript deprecations. Furthermore, the CI workflows (`.github/workflows`) are adjusted to temporarily downgrade and restore TypeScript `ignoreDeprecations` options during typecheck steps, ensuring robust testing across different TypeScript versions. This comprehensive **maintenance** and **bug fix** effort ensures Docusaurus projects can be built reliably with newer TypeScript versions and improves overall project stability.

This commit performs **maintenance** on the project's **CI/CD pipeline** by implementing fixes for the **npm trusted publishing workflow**. It refines the `.github/workflows/publish.yml` GitHub Actions configuration to remove a temporary branch, clarify NPM distribution tag descriptions, and ensure Lerna publish commands explicitly push Git tags. Additionally, the `lerna.json` file is updated to bump the project's internal version from `3.9.2-alpha.1` to `3.9.2`. This ensures a more robust and accurate process for publishing NPM packages by correctly managing Git tags and distribution labels.

This commit introduces a **new CI/CD capability** by adding a **Trusted Publishing release workflow** to the project's GitHub Actions. The new workflow, defined in `.github/workflows/publish.yml`, enables **manual dispatch-triggered NPM package releases**, allowing users to specify the version and tag for publishing. It integrates with Lerna to manage the official release process, thereby enhancing the **reliability and control** over the project's **NPM package distribution**. This **infrastructure improvement** streamlines the release pipeline and provides a more robust mechanism for publishing new versions.

This commit provides a **bug fix** for the **Docusaurus MDX loader** by correcting a critical typo in the `createMDXLoader.ts` file. Specifically, it changes the misspelled environment variable `N0DE_ENV` to the correct `NODE_ENV` within the `normalizeOptions` function. This **maintenance** update ensures the loader accurately reads the standard Node.js environment variable, which is essential for environment-dependent logic and proper processing of MDX files across different deployment stages.

This commit performs a **maintenance chore** by updating the project's **version control configuration**. Specifically, it modifies the `.gitignore` file to include entries for the `.claude` and `.codex` directories. This change ensures that local development artifacts and temporary files generated by AI coding assistants are automatically excluded from Git tracking, thereby maintaining a clean and focused repository.

This commit significantly **improves the developer experience (DX)** for the **Git Eager VCS strategy** within the `docusaurus-utils` package. It introduces a new utility function, `isGitInsideWorktree`, to programmatically determine if a given directory is part of a Git worktree. This utility is then used to **refactor the `vcsGitEager` initialization**, providing more specific and less "frightening" error messages when a site is not a Git worktree, while also temporarily disabling initial error logging. These **fixes** ensure a smoother setup process and clearer feedback for users, supported by new comprehensive test suites for various Git scenarios.

This commit **stabilizes** the Docusaurus "Faster" features by promoting `future.experimental_faster` to `future.faster` across the codebase. It introduces a **new capability**, `future.v4.fasterByDefault`, which automatically enables these performance enhancements when `v4: true` is set in the configuration, while still allowing granular overrides. This involves a significant **refactoring** of **Docusaurus core**, **bundler**, and various **content plugins** to adopt the new configuration property. Additionally, it includes **bug fixes** and **maintenance** to declare `@docusaurus/faster` as an optional peer dependency of `@docusaurus/core`, resolving Yarn PnP compatibility issues in the build system. This ensures smoother adoption of these faster features and better compatibility for projects using Docusaurus v4.

This commit **promotes the `experimental_storage` configuration to a stable, top-level `storage` property** within the Docusaurus `siteConfig`. It **introduces a new `future.v4.siteStorageNamespacing` flag** to control future storage behavior, signifying an upcoming change in how site storage is managed. The **configuration validation** and **internal storage utilities** are updated to reflect this new stable API, ensuring proper schema enforcement and functionality. This **feature stabilization** and **API evolution** impacts how Docusaurus sites configure and interact with client-side storage, with corresponding **documentation updates** for users.

This commit introduces a **maintenance** change to the **CI/CD publishing workflow**, specifically targeting **canary and trusted releases**. It **disables Yarn caching** within the `.github/workflows/publish.yml` configuration to prevent potential security risks. By ensuring that all dependencies are freshly fetched rather than relying on cached artifacts during these critical release processes, this change enhances the **security and integrity of published packages**.

This commit provides a **documentation update** to the **website's Markdown features guide**, specifically for **math equations**. It revises the recommended syntax, advising users to now employ ````latex```math```` fenced code blocks instead of the older `$$` delimiters. This **maintenance** change affects all current and versioned documentation for math equation usage, ensuring consistency and promoting the preferred method. The update guides users towards a more robust and potentially better-supported way to render mathematical expressions within the platform's content.

This commit introduces a **new capability** to the **Docusaurus CLI**, enhancing the `write-heading-ids` command with `--syntax`, `--migrate`, and `--overwrite` options. Users can now specify the desired heading ID syntax (e.g., 'classic' or 'mdx-comment') and control the migration or overwriting of existing IDs in their Markdown and MDX files. This involved creating a new **`markdownHeadingIdUtils`** module to encapsulate robust parsing and writing logic for different syntaxes, alongside **refactoring** existing heading ID extraction in the `mdx-loader` and adding **comprehensive unit tests**. The **documentation** for both the CLI and markdown features has been updated, significantly improving **content consistency** and **developer experience** when managing heading IDs.

This commit delivers a **bug fix** and **usability improvement** for the **Docusaurus CLI command `write-heading-ids`**. Specifically, it addresses an issue where the command would not behave correctly when invoked without any specified files or when no markdown files were discovered in the project. The change ensures the `writeHeadingIds` utility now gracefully handles these edge cases, preventing potential errors and providing a clear **warning message** to the user if no markdown files are found to process. This enhances the robustness and user-friendliness of the heading ID generation feature.

This commit introduces a **new feature** to the **Docusaurus MDX loader**, allowing users to define **explicit heading IDs** directly within their Markdown and MDX content using **comment syntax**. The **remark plugin** in `packages/docusaurus-mdx-loader/src/remark/headings/index.ts` has been enhanced to process `<!-- #id -->` or `{/* #id */}` comments, assigning custom IDs to headings and improving content authoring flexibility. This update includes necessary **type definition changes** in `packages/docusaurus-mdx-loader/src/types.d.mts` and comprehensive **documentation** in `website/docs/guides/markdown-features/markdown-features-toc.mdx` to guide users on the new method. The **MDX processing pipeline** is now more robust, providing a modern alternative to the legacy `{ #id }` syntax for managing heading anchors.

This commit **refactors** the **unit tests** for the **Docusaurus MDX loader's remark heading plugin**. The tests in `packages/docusaurus-mdx-loader/src/remark/headings/__tests__/index.test.ts` are now updated to **support both Markdown and MDX syntax** for heading ID generation, replacing previous commonmark-only testing. This **maintenance** work improves the overall test structure and introduces a new helper function, ensuring more comprehensive and robust validation of heading ID behavior across different content formats.

This commit **introduces new documentation** by adding `AGENTS.md`, providing a comprehensive guide for **AI coding agents**. This **documentation enhancement** details the project overview, monorepo structure, commands, and contribution guidelines relevant to these agents. Additionally, it includes a minor **maintenance update** to `project-words.txt` by adding 'toposort' to the custom word list. The primary impact is to improve the onboarding and understanding for developers interacting with or contributing to the **AI coding agent subsystem**.

This commit **upgrades** the **Algolia DocSearch integration** to version 4.5, enhancing the project's search capabilities. It also addresses and **fixes type-checking issues** that arose during the upgrade, specifically by adding an empty resolution and incorporating the AI SDK to unblock library type-checking. This work ensures the search functionality remains robust and compatible with the latest DocSearch features, while significantly improving overall code stability and preventing type-related errors within the project's dependencies. The primary impact is on the **search infrastructure** and **developer experience** by maintaining type safety and leveraging an updated external library.