From 82aedc387d363542a6e910e925513fbbe901253a Mon Sep 17 00:00:00 2001
From: rockywall <tanvird556@gmail.com>
Date: Sat, 6 Dec 2025 10:44:50 +0600
Subject: [PATCH] Update mathjax3 install instructions in markdown guides

Replaces single npm install command with code-group examples for both npm and pnpm, and adds a note recommending markdown-it-mathjax3@^4 due to breaking changes in newer versions. Changes applied across all language versions of the markdown guide.
---
 docs/en/guide/markdown.md | 17 +++++++++++++++--
 docs/es/guide/markdown.md | 17 +++++++++++++++--
 docs/fa/guide/markdown.md | 17 +++++++++++++++--
 docs/ja/guide/markdown.md | 19 ++++++++++++++++---
 docs/ko/guide/markdown.md | 17 +++++++++++++++--
 docs/pt/guide/markdown.md | 17 +++++++++++++++--
 docs/ru/guide/markdown.md | 17 +++++++++++++++--
 docs/zh/guide/markdown.md | 17 +++++++++++++++--
 8 files changed, 121 insertions(+), 17 deletions(-)

diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index f6cd8831..ab2648a1 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -948,10 +948,23 @@ and include it like this:
 
 This is currently opt-in. To enable it, you need to install `markdown-it-mathjax3` and set `markdown.math` to `true` in your config file:
 
-```sh
-npm add -D markdown-it-mathjax3^4
+::: code-group
+
+```sh [npm]
+$ npm add -D markdown-it-mathjax3@^4
+```
+
+```sh [pnpm]
+$ pnpm add -D markdown-it-mathjax3@^4
 ```
 
+:::
+
+::: tip NOTE
+Use `markdown-it-mathjax3@^4` instead of the latest version.  
+Newer releases introduce breaking changes that are not compatible with VitePress.
+:::
+
 ```ts [.vitepress/config.ts]
 export default {
   markdown: {
diff --git a/docs/es/guide/markdown.md b/docs/es/guide/markdown.md
index 82a01e7e..b00520c4 100644
--- a/docs/es/guide/markdown.md
+++ b/docs/es/guide/markdown.md
@@ -843,10 +843,23 @@ Observe que esto no genera errores si el archivo no está presente. Por lo tanto
 
 Esto es actualmente opcional. Para activarlo, necesita instalar `markdown-it-mathjax3` y definir `markdown.math` como `true` en su archivo de configuración:
 
-```sh
-npm add -D markdown-it-mathjax3^4
+::: code-group
+
+```sh [npm]
+$ npm add -D markdown-it-mathjax3@^4
+```
+
+```sh [pnpm]
+$ pnpm add -D markdown-it-mathjax3@^4
 ```
 
+:::
+
+::: tip NOTE
+Use `markdown-it-mathjax3@^4` instead of the latest version.  
+Newer releases introduce breaking changes that are not compatible with VitePress.
+:::
+
 ```ts [.vitepress/config.ts]
 export default {
   markdown: {
diff --git a/docs/fa/guide/markdown.md b/docs/fa/guide/markdown.md
index 3957d6c7..f8a3713c 100644
--- a/docs/fa/guide/markdown.md
+++ b/docs/fa/guide/markdown.md
@@ -832,10 +832,23 @@ export default config
 
 در حال حاضر این گزینه اختیاری است. برای فعال‌سازی آن، باید `markdown-it-mathjax3` را نصب کرده و `markdown.math` را در فایل پیکربندی خود به `true` تنظیم کنید:
 
-```sh
-npm add -D markdown-it-mathjax3^4
+::: code-group
+
+```sh [npm]
+$ npm add -D markdown-it-mathjax3@^4
+```
+
+```sh [pnpm]
+$ pnpm add -D markdown-it-mathjax3@^4
 ```
 
+:::
+
+::: tip NOTE
+Use `markdown-it-mathjax3@^4` instead of the latest version.  
+Newer releases introduce breaking changes that are not compatible with VitePress.
+:::
+
 ```ts [.vitepress/config.ts]
 export default {
   markdown: {
diff --git a/docs/ja/guide/markdown.md b/docs/ja/guide/markdown.md
index bb1710d9..e9c3df50 100644
--- a/docs/ja/guide/markdown.md
+++ b/docs/ja/guide/markdown.md
@@ -953,9 +953,22 @@ VS Code のリージョンの代わりに、ヘッダーアンカーを使って
 
 この機能はオプトインです。利用するには `markdown-it-mathjax3` をインストールし、設定ファイルで `markdown.math` を `true` に設定します。
 
- ```sh
- npm add -D markdown-it-mathjax3^4
- ```
+::: code-group
+
+```sh [npm]
+$ npm add -D markdown-it-mathjax3@^4
+```
+
+```sh [pnpm]
+$ pnpm add -D markdown-it-mathjax3@^4
+```
+
+:::
+
+::: tip NOTE
+Use `markdown-it-mathjax3@^4` instead of the latest version.  
+Newer releases introduce breaking changes that are not compatible with VitePress.
+:::
 
  ```ts [.vitepress/config.ts]
  export default {
diff --git a/docs/ko/guide/markdown.md b/docs/ko/guide/markdown.md
index 04fa1bc5..8ea87c74 100644
--- a/docs/ko/guide/markdown.md
+++ b/docs/ko/guide/markdown.md
@@ -879,10 +879,23 @@ Can be created using `.foorc.json`.
 
 선택 사항입니다. 활성화하려면 `markdown-it-mathjax3`를 설치하고 설정 파일에서 `markdown.math`를 `true`로 설정해야 합니다:
 
-```sh
-npm add -D markdown-it-mathjax3^4
+::: code-group
+
+```sh [npm]
+$ npm add -D markdown-it-mathjax3@^4
+```
+
+```sh [pnpm]
+$ pnpm add -D markdown-it-mathjax3@^4
 ```
 
+:::
+
+::: tip NOTE
+Use `markdown-it-mathjax3@^4` instead of the latest version.  
+Newer releases introduce breaking changes that are not compatible with VitePress.
+:::
+
 ```ts [.vitepress/config.ts]
 export default {
   markdown: {
diff --git a/docs/pt/guide/markdown.md b/docs/pt/guide/markdown.md
index d52769fc..219088b1 100644
--- a/docs/pt/guide/markdown.md
+++ b/docs/pt/guide/markdown.md
@@ -842,10 +842,23 @@ Observe que isso não gera erros se o arquivo não estiver presente. Portanto, a
 
 Isso é atualmente opcional. Para ativá-lo, você precisa instalar `markdown-it-mathjax3` e definir `markdown.math` como `true` no seu arquivo de configuração:
 
-```sh
-npm add -D markdown-it-mathjax3^4
+::: code-group
+
+```sh [npm]
+$ npm add -D markdown-it-mathjax3@^4
+```
+
+```sh [pnpm]
+$ pnpm add -D markdown-it-mathjax3@^4
 ```
 
+:::
+
+::: tip NOTE
+Use `markdown-it-mathjax3@^4` instead of the latest version.  
+Newer releases introduce breaking changes that are not compatible with VitePress.
+:::
+
 ```ts [.vitepress/config.ts]
 export default {
   markdown: {
diff --git a/docs/ru/guide/markdown.md b/docs/ru/guide/markdown.md
index 4dcd2a6b..a24aa582 100644
--- a/docs/ru/guide/markdown.md
+++ b/docs/ru/guide/markdown.md
@@ -950,10 +950,23 @@ export default config
 
 В настоящее время эта фича предоставляется по желанию. Чтобы включить её, вам нужно установить `markdown-it-mathjax3` и установить значение `true` для опции `markdown.math` в вашем файле конфигурации:
 
-```sh
-npm add -D markdown-it-mathjax3^4
+::: code-group
+
+```sh [npm]
+$ npm add -D markdown-it-mathjax3@^4
+```
+
+```sh [pnpm]
+$ pnpm add -D markdown-it-mathjax3@^4
 ```
 
+:::
+
+::: tip NOTE
+Use `markdown-it-mathjax3@^4` instead of the latest version.  
+Newer releases introduce breaking changes that are not compatible with VitePress.
+:::
+
 ```ts [.vitepress/config.ts]
 export default {
   markdown: {
diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md
index 124c7249..79448919 100644
--- a/docs/zh/guide/markdown.md
+++ b/docs/zh/guide/markdown.md
@@ -842,10 +842,23 @@ Can be created using `.foorc.json`.
 
 现在这是可选的。要启用它，需要安装 `markdown-it-mathjax3`，在配置文件中设置`markdown.math` 为 `true`：
 
-```sh
-npm add -D markdown-it-mathjax3^4
+::: code-group
+
+```sh [npm]
+$ npm add -D markdown-it-mathjax3@^4
+```
+
+```sh [pnpm]
+$ pnpm add -D markdown-it-mathjax3@^4
 ```
 
+:::
+
+::: tip NOTE
+Use `markdown-it-mathjax3@^4` instead of the latest version.  
+Newer releases introduce breaking changes that are not compatible with VitePress.
+:::
+
 ```ts [.vitepress/config.ts]
 export default {
   markdown: {