fix: unescape unexpected symbols in sidebar (#98)

Author: JounQin

.changeset/stupid-sloths-relax.md

@@ -0,0 +1,5 @@
+---
+"@alauda/doom": patch
+---
+
+fix: unescape unexpected symbols in sidebar

docs/en/start.mdx

@@ -1,5 +1,5 @@
 ---
-sourceSHA: b7fe69a866c3e8893f7eddf6720d3366865e8e03b58658225bdd926ad71d6c87
+sourceSHA: e8aa2b84d58ff17ca57bc7aa4aa8c4479944ae37b389df87676d487ab1ababe9
 ---
 
 # Getting Started \{#start}
@@ -45,7 +45,7 @@ Then initialize a configuration file `doom.config.yml`:
 title: My Docs
 ```
 
-Also create a `tsconfig.json` file with the following content:
+Also create `tsconfig.json` 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 with type safety in `.mdx` files.
+This allows you to safely use the global components provided by doom in `.mdx` files with type safety.
 
 ## 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
@@ -148,11 +148,11 @@ Run `yarn build` to build the production code. After building, static files will
 
 ### Local Preview \{#serve}
 
-Run `yarn serve` to preview the built static files. Note that if you used `-b` or `-p` parameters during build, you need to use the same `-b` and `-p` parameters during preview.
+Run `yarn serve` to preview the built static files. Note that if you used `-b`, `-p` parameters during build, you need to use the same `-b`, `-p` parameters during preview.
 
 ### 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}
 
@@ -175,24 +175,24 @@ Options:
   -h, --help               display help for command
 ```
 
-- The `-g, --glob` parameter is required and 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 caused by command line parsing. Examples:
+- The `-g, --glob` parameter is required and specifies the directories or files to translate, supporting `glob` syntax. Note that the parameter value must be quoted to avoid unexpected behavior from the shell. 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 determines 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. For `<root>/<source>/abc.mdx` documents referencing `./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. For `<root>/<source>/abc.mdx` documents referencing `./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`.
-  - 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. For `<root>/<source>/abc.mdx` documents referencing `./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. `yarn translate -g '*'` will translate all documents under `<root>/<source>`.
+- 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 changes the asset reference paths to the source paths. Examples:
+  - When enabled:
+    1. `/<source>/abc.jpg` will copy `<root>/public/<source>/abc.jpg` to `<root>/public/<target>/abc.jpg` and update the document reference path to `/<target>/abc.jpg`.
+    2. In `<root>/<source>/abc.mdx`, a reference to `./assets/xyz.jpg` will copy `<root>/<source>/assets/xyz.jpg` to `<root>/<target>/assets/xyz.jpg`, keeping the image reference path unchanged.
+    3. In `<root>/<source>/abc.mdx`, a reference to `./assets/<source>/xyz.jpg` will copy `<root>/<source>/assets/<source>/xyz.jpg` to `<root>/<target>/assets/<target>/xyz.jpg` and update the document reference path to `./assets/<target>/xyz.jpg`.
+  - When not enabled:
+    1. For `/<source>/abc.jpg`, if `<root>/public/<target>/abc.jpg` exists, the document reference path will be updated to `/<target>/abc.jpg`; otherwise, the image reference path remains unchanged.
+    2. In `<root>/<source>/abc.mdx`, if `<root>/<target>/assets/<target>/xyz.jpg` exists, the reference path will be updated 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.
 :::
 
 :::tip
-The translation feature requires configuring the `AZURE_OPENAI_API_KEY` environment variable locally. 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:
@@ -201,7 +201,7 @@ You can control translation behavior in the document metadata:
 i18n:
   title:
     en: DevOps Connectors
-  additionalPrompts: 'The Connectors in this document are proper nouns and should not be translated'
+  additionalPrompts: 'The term Connectors in this document is a proper noun and should not be translated'
   disableAutoTranslation: false
 title: DevOps Connectors
 ```
@@ -211,7 +211,7 @@ For more configuration, please refer to [Translation Configuration](./usage/conf
 ### Exporting PDF \{#export}
 
 :::warning
-Please run `yarn build` before executing the export operation.
+Please run `yarn build` before performing the export operation.
 :::
 
 ```sh
@@ -231,9 +231,9 @@ Options:
   -h, --help         display help for command
 ```
 
-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.
+Run `yarn export` to export the documentation as PDF files. Note that if you used `-b`, `-p` parameters during build, you need to use the same `-b`, `-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 build. Locally, you can set the following environment variable to speed up downloads:
+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"
@@ -263,7 +263,7 @@ Options:
   ```js
   import doom from '@alauda/doom/eslint'
 
-  export default await doom(new URL('docs', import.meta.url))
+  export default doom(new URL('docs', import.meta.url))
   ```
 
 - `cspell.config.mjs`:
@@ -272,7 +272,7 @@ Options:
   export { default } from '@alauda/doom/cspell'
   ```
 
-We also agree that the `.cspell` folder in the current working directory (`CWD`) is used 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

docs/zh/start.mdx

@@ -261,7 +261,7 @@ Options:
   ```js
   import doom from '@alauda/doom/eslint'
 
-  export default await doom(new URL('docs', import.meta.url))
+  export default doom(new URL('docs', import.meta.url))
   ```
 
 - `cspell.config.mjs`:

eslint.config.js

@@ -5,6 +5,7 @@ import react from '@eslint-react/eslint-plugin'
 import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescript'
 import { importX } from 'eslint-plugin-import-x'
 import * as reactHooks from 'eslint-plugin-react-hooks'
+import * as regexp from 'eslint-plugin-regexp'
 import { config, configs } from 'typescript-eslint'
 
 import doom from '@alauda/doom/eslint'
@@ -19,6 +20,7 @@ export default config(
   importX.flatConfigs.typescript,
   react.configs.recommended,
   reactHooks.configs['recommended-latest'],
+  regexp.configs['flat/recommended'],
   {
     files: ['**/*.{ts,tsx}'],
     extends: [

fixture-docs/en/apis/kubernetes_apis/openshiftpipelinesascodes.mdx

@@ -2,6 +2,6 @@
 weight: 180
 ---
 
-# OpenShiftPipelinesAsCode \[operator.tekton.dev/v1alpha1]
+# OpenShiftPipelinesAsCode \[operator.tekton.dev/v1alpha1\]
 
 <K8sCrd name="openshiftpipelinesascodes.operator.tekton.dev" />

fixture-docs/en/index.mdx

@@ -1,9 +1,6 @@
----
----
-
 import { useI18n } from '@rspress/core/runtime'
 
-# {useI18n()('prod_intro')}
+# {useI18n()('prod_intro')} \{#prod_intro_i18n\}
 
 <Term name="company" /> <Term name="product" /> <Term name="productShort" />
 

fixture-docs/en/test-escape.md

@@ -0,0 +1 @@
+# Test \[Escape\] \{#prod_intro_i18n\}

fixture-docs/ru/apis/kubernetes_apis/openshiftpipelinesascodes.mdx

@@ -1,8 +1,8 @@
 ---
 weight: 180
-sourceSHA: 80529755e86835c2c5f99b347fcc632b324a0b842601501c12298a32885a57d0
+sourceSHA: 8733482a1d5451a90df6860b2d69dbf076c039f6ee3ca5654aa8416f8c4d7bf6
 ---
 
-# OpenShiftPipelinesAsCode \[operator.tekton.dev/v1alpha1]
+# OpenShiftPipelinesAsCode \[operator.tekton.dev/v1alpha1\]
 
 <K8sCrd name="openshiftpipelinesascodes.operator.tekton.dev" />

fixture-docs/ru/code-title.md

@@ -0,0 +1,7 @@
+---
+sourceSHA: e431f3377becf3888988f83837a2b714c8e0a3330d6aa1cd69611b93a22ba61a
+---
+
+```js title="Hello World"
+console.log('Hello, World!')
+```

fixture-docs/ru/index.mdx

@@ -1,23 +1,23 @@
 ---
-sourceSHA: e752331d6b37e30a460ac29cb4eb13f753c324f2f938af8cf631cb446b280819
+sourceSHA: 7f15c9e90978c98f9621efe840a5f243bd12b7c53b495af9b5a0c03fdd349e91
 ---
 
 import { useI18n } from '@rspress/core/runtime'
 
-# {useI18n()('prod_intro')}
+# {useI18n()('prod_intro')} \{#prod_intro_i18n}
 
 <Term name="company" />
 
 <Term name="product" />
 
 <Term name="productShort" />
 
-Следующие спецификации должны быть соблюдены в процессе перевода для интернационализации:
+Следующие требования должны соблюдаться в процессе перевода для интернационализации:
 
-- Структура директорий многоязычных документов (`doc/en`) должна быть идентична документам в директории `doc/zh`, что обеспечит точное совпадение ссылок на многоязычные документы за исключением идентификатора языка.
+- Структура каталогов многоязычных документов (`doc/en`) должна быть идентична структуре документов в каталоге `doc/zh`, обеспечивая, что ссылки на многоязычные документы будут точно такими же, за исключением идентификатора языка.
 
   ::: danger
-  Если для перевода используется инструмент автоматического перевода, нет необходимости беспокоиться об этом вопросе, так как инструмент автоматического перевода автоматически сгенерирует структуру директорий для документов целевого языка на основе `doc/zh`.
+  Если для перевода используется автоматический инструмент перевода, беспокоиться об этом не нужно, так как автоматический инструмент перевода автоматически создаст структуру каталогов для документов целевого языка на основе `doc/zh`.
   :::
 
 <Tabs>