feat: integrate eslint-plugin-mdx with remark-lint

.changeset/silly-llamas-argue.md

@@ -0,0 +1,5 @@
+---
+"@alauda/doom": minor
+---
+
+feat: integrate `eslint-plugin-mdx` with `remark-lint`

.nvmrc

@@ -1 +1 @@
-v20.19.2
+v24.3.0

docs/en/start.mdx

@@ -1,5 +1,5 @@
 ---
-sourceSHA: ae0b93052a9ac54c78d33e4bd8516f66409fb0355f52e0ce069d53cf0138a992
+sourceSHA: e22f8a9da520d8a45867b9da3ba498f4884f9c4cc937fa5b9fc54a80a1bc391a
 ---
 
 # Getting Started \{#start}
@@ -12,19 +12,19 @@ First, you can create a new directory with the following command:
 mkdir my-docs && cd my-docs
 ```
 
-Run `npm init -y` to initialize a project. You can use npm, yarn, or pnpm to install doom:
+Run `npm init -y` to initialize a project. You can install doom using npm, yarn, or pnpm:
 
 <PackageManagerTabs command="install -D @alauda/doom typescript" />
 
 Then create files with the following commands:
 
 ```bash
-# Create docs directories, default supports bilingual Chinese and English
+# Create docs directories, with default support for bilingual Chinese and English
 mkdir docs/en && echo '# Hello World' > docs/en/index.md
 mkdir docs/zh && echo '# 你好世界' > docs/zh/index.md
 ```
 
-Add the following scripts to `package.json`:
+Add the following scripts to your `package.json`:
 
 ```json
 {
@@ -45,7 +45,7 @@ Then initialize a configuration file `doom.config.yml`:
 title: My Docs
 ```
 
-Also create `tsconfig.json` with the following content:
+Also create a `tsconfig.json` file with the following content:
 
 ```jsonc
 {
@@ -72,7 +72,7 @@ Finally, create a `global.d.ts` file with the following content:
 /// <reference types="@alauda/doom/runtime" />
 ```
 
-This allows you to safely use the global components provided by doom in `.mdx` files with type safety.
+This allows you to safely use the global components provided by doom with type safety in `.mdx` files.
 
 ## CLI Tool \{#cli}
 
@@ -121,7 +121,7 @@ For more configuration, please refer to [Configuration](./usage/configuration)
 
 ### Starting the Development Server \{#dev}
 
-Run `yarn dev` to start the development server; the browser will automatically open the documentation homepage.
+Run `yarn dev` to start the development server, the browser will automatically open the documentation homepage.
 
 ```sh
 doom dev -h
@@ -152,7 +152,7 @@ Run `yarn serve` to preview the built static files. Note that if you used `-b` o
 
 ### Using Scaffolding Templates \{#new}
 
-Run `yarn new` to generate projects, modules, or documentation using scaffolding templates.
+Run `yarn new` to generate projects, modules, or documentation from scaffolding templates.
 
 ### Translating Documentation \{#translate}
 
@@ -170,29 +170,29 @@ Arguments:
 Options:
   -s, --source <language>  Document source language, one of en, zh, ru (default: "en")
   -t, --target <language>  Document target language, one of en, zh, ru (default: "zh")
-  -g, --glob <path...>     Glob patterns for source dirs/files
+  -g, --glob <path...>     Glob patterns of source dirs/files to translate
   -C, --copy [boolean]     Whether to copy relative assets to the target directory instead of following links (default: false)
   -h, --help               display help for command
 ```
 
-- The `-g, --glob` parameter is required. You can specify the directories or paths of files to translate, supporting `glob` syntax. Note that the parameter value must be quoted to avoid unexpected behavior from the command line parser. Examples:
+- The `-g, --glob` parameter is required and can specify the directories or files to translate, supporting `glob` syntax. Note that the parameter value must be quoted to avoid unexpected behavior caused by command line parsing. Examples:
   1. `yarn translate -g abc xyz` will translate all documents under `<root>/<source>/abc` and `<root>/<source>/xyz` to `<root>/<target>/abc` and `<root>/<target>/xyz` respectively.
   2. `yarn translate -g '*'` will translate all document files under `<root>/<source>`.
-- The `-C, --copy` parameter is optional. It controls whether to copy local asset files to the target directory when the target file does not exist. The default is `false`, which means changing the asset reference paths to the source paths. Examples:
+- The `-C, --copy` parameter is optional and controls whether to copy local asset files to the target directory when the target file does not exist. The default is `false`, which means changing the asset reference path to the source path. Examples:
   - When this parameter is enabled:
-    1. When translating `/<source>/abc.jpg`, it will copy `<root>/public/<source>/abc.jpg` to `<root>/public/<target>/abc.jpg` and modify the reference path in the document to `/<target>/abc.jpg`.
-    2. In `<root>/<source>/abc.mdx`, when translating `./assets/xyz.jpg`, it will copy `<root>/<source>/assets/xyz.jpg` to `<root>/<target>/assets/xyz.jpg`, and the image reference path remains unchanged.
-    3. In `<root>/<source>/abc.mdx`, when translating `./assets/<source>/xyz.jpg`, it will copy `<root>/<source>/assets/<source>/xyz.jpg` to `<root>/<target>/assets/<target>/xyz.jpg` and modify the reference path in the document to `./assets/<target>/xyz.jpg`.
+    1. When translating `/<source>/abc.jpg`, `<root>/public/<source>/abc.jpg` will be copied to `<root>/public/<target>/abc.jpg`, and the reference path in the document will be changed to `/<target>/abc.jpg`.
+    2. For `./assets/xyz.jpg` in `<root>/<source>/abc.mdx`, the file `<root>/<source>/assets/xyz.jpg` will be copied to `<root>/<target>/assets/xyz.jpg`, and the image reference path remains unchanged.
+    3. For `./assets/<source>/xyz.jpg` in `<root>/<source>/abc.mdx`, the file `<root>/<source>/assets/<source>/xyz.jpg` will be copied to `<root>/<target>/assets/<target>/xyz.jpg`, and the reference path in the document will be changed to `./assets/<target>/xyz.jpg`.
   - When this parameter is not enabled:
     1. When translating `/<source>/abc.jpg`, if `<root>/public/<target>/abc.jpg` exists, the reference path in the document will be changed to `/<target>/abc.jpg`; otherwise, the image reference path remains unchanged.
-    2. In `<root>/<source>/abc.mdx`, when translating `./assets/<source>/xyz.jpg`, if `<root>/<target>/assets/<target>/xyz.jpg` exists, the reference path will be changed to `./assets/<target>/xyz.jpg`; otherwise, it will be changed to `../<source>/assets/<target>/xyz.jpg`.
+    2. For `./assets/<source>/xyz.jpg` in `<root>/<source>/abc.mdx`, if `<root>/<target>/assets/<target>/xyz.jpg` exists, the reference path in the document will be changed to `./assets/<target>/xyz.jpg`; otherwise, it will be changed to `../<source>/assets/<target>/xyz.jpg`.
 
 :::warning
-Specifically, if you use `-g '*'` for full translation, the file lists of `source` and `target` directories will be compared, and unmatched `target` files except for `internalRoutes` will be automatically deleted.
+Specifically, if you use `-g '*'` for full translation, the file lists of the `source` and `target` directories will be compared, and unmatched `target` files except for `internalRoutes` will be automatically deleted.
 :::
 
 :::tip
-The translation feature requires the local environment variable `AZURE_OPENAI_API_KEY` to be configured. Please contact your team Leader to obtain it.
+The translation feature requires the local environment variable `AZURE_OPENAI_API_KEY` to be configured. Please contact your team leader to obtain it.
 :::
 
 You can control translation behavior in the document metadata:
@@ -211,7 +211,7 @@ For more configuration, please refer to [Translation Configuration](./usage/conf
 ### Exporting PDF \{#export}
 
 :::warning
-Please run `yarn build` to build the project before exporting.
+Please run the `yarn build` command before exporting.
 :::
 
 ```sh
@@ -231,15 +231,15 @@ Options:
   -h, --help         display help for command
 ```
 
-Run `yarn export` to export the documentation as PDF files. Note that if you used `-b` or `-p` parameters during build, you need to use the same `-b` and `-p` parameters during export.
+Run `yarn export` to export the documentation as a PDF file. Note that if you used `-b` or `-p` parameters during build, you need to use the same `-b` and `-p` parameters during export.
 
 The export feature depends on [`playwright`](https://playwright.dev). For CI pipelines, please use `build-harbor.alauda.cn/frontend/playwright-runner:doom` as the base image for dependency installation and documentation building. Locally, you can set the following environment variable to speed up downloads:
 
 ```dotenv title=".env.yarn"
 PLAYWRIGHT_DOWNLOAD_HOST="https://cdn.npmmirror.com/binaries/playwright"
 ```
 
-Besides exporting a unified full-site PDF, `doom` also supports exporting a single PDF file for a specified entry. For more configuration, please refer to [Documentation Export Configuration](./usage/configuration#export)
+In addition to exporting a complete PDF document for the entire site, `doom` also supports exporting a single PDF file for a specified entry. For more configuration, please refer to [Documentation Export Configuration](./usage/configuration#export)
 
 ### Documentation Linting \{#lint}
 
@@ -252,10 +252,12 @@ Usage: doom lint [options] [root]
 Lint the documentation
 
 Arguments:
-  root        Root directory of the documentation
+  root                  Root directory of the documentation
 
 Options:
-  -h, --help  display help for command
+  -g, --glob <path...>  Glob patterns of source dirs/files to lint (default: "**/*.{js,jsx,ts,tsx,md,mdx}")
+  --no-cspell           Disable cspell linting
+  -h, --help            display help for command
 ```
 
 `doom lint` is based on [`ESLint`](https://eslint.org/) and [`cspell`](https://cspell.org/). For a better experience in your editor, you can install the corresponding plugins [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) / [CSpell](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker), then create the corresponding configuration files:
@@ -274,11 +276,11 @@ Options:
   export { default } from '@alauda/doom/cspell'
   ```
 
-We also conventionally use the `.cspell` folder under the current working directory (`CWD`) to store CSpell dictionary files. For example, you can create `.cspell/k8s.txt`:
+We also agree that the `.cspell` folder under the current working directory (`CWD`) is used to store CSpell dictionary files. For example, you can create `.cspell/k8s.txt`:
 
 ```txt
 k8s
 kubernetes
 ```
 
-For more configuration, please refer to [Documentation Linting Configuration](./usage/configuration#lint)
+For more configuration, please refer to [Lint Configuration](./usage/configuration#lint)