fix: known issues

Author: JounQin

.github/workflows/ci.yml

@@ -39,3 +39,4 @@ jobs:
         run: yarn run-p build docs lint typecov
         env:
           PARSER_NO_WATCH: true
+          RAW_TERMS_URL: ${{ secrets.RAW_TERMS_URL }}

docs/en/start.mdx

@@ -1,5 +1,5 @@
 ---
-sourceSHA: b375fe90bc3c10daf2cf1af94d73c48daa4fd307ee7d1aad87947d4fe7b6eb1f
+sourceSHA: abdacac359849f6bc46d4b115a537545544edd8d5bee65fe8732cd3cea8ec8e9
 ---
 
 # Start \{#start}
@@ -116,7 +116,7 @@ Commands:
 
 ### Start Development Service \{#dev}
 
-Run `yarn dev` to start the development service, and the browser will open the documentation homepage automatically.
+Run `yarn dev` to start the development service, and the browser will automatically open the documentation homepage.
 
 ```sh
 doom dev -h
@@ -188,7 +188,7 @@ In particular, when using `-g '*'` for full translation, the file lists of the `
 :::
 
 :::tip
-The translation function must have the local environment variable `AZURE_OPENAI_API_KEY` configured. Please contact your team leader for this information.
+The translation function requires the local environment variable `AZURE_OPENAI_API_KEY` to be configured. Please contact your team leader for this information.
 :::
 
 Metadata can be used in the document to control translation behavior:

docs/en/usage/configuration.md

@@ -1,7 +1,7 @@
 ---
 description: Configure `doom` documentation tool
 weight: 1
-sourceSHA: 8c04921d3d667333d5dd810c99aa189cd38774116eb48bf9425944810e400344
+sourceSHA: e06d0647311a571bc2a3584ed125b83d6f6ab016738b27879f59aa32984fdd92
 ---
 
 # Configuration {#configuration}
@@ -209,3 +209,10 @@ The final output should only include the results from the last step, and previou
 ```yaml
 editRepoBaseUrl: alauda/doom/tree/main/docs # The prefix https://github.com/ can be omitted; it only takes effect when the `-R, --edit-repo` command line flag is enabled.
 ```
+
+## Document Linting Configuration {#lint}
+
+```yaml
+lint:
+  cspellOptions: # optional, cspell configuration options, refer to https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-eslint-plugin#options
+```

docs/en/usage/deploy.md

@@ -3,7 +3,7 @@ description: >-
   After completing the project development, we can deploy the project to the ACP
   platform.
 weight: 8
-sourceSHA: b8be77fb7d7f9a2fb5fc34de8b0423df711c0220a02acad1c602f6cb2d3ab36a
+sourceSHA: 3bb40af83c43ea6f891a330af703b5cb17133d17970dea35cde1a796e5b7b246
 ---
 
 # Deployment

docs/en/usage/reference.md

@@ -1,6 +1,6 @@
 ---
 weight: 7
-sourceSHA: 55d1c3e5a0991772e572dba8f769e80a1b6e32e84abcd3514caaf0028872f785
+sourceSHA: ebb89470ba5bca9d172ff55b57b112b9a0376eec28cc74cdd7c8248f3772de44
 ---
 
 # Referencing Documents

docs/zh/start.mdx

@@ -110,6 +110,8 @@ Commands:
   help [command]                  display help for command
 ```
 
+更多配置请参考[配置](./usage/configuration)
+
 ### 启动开发服务 \{#dev}
 
 执行 `yarn dev` 启动开发服务，浏览器会自动打开文档首页
@@ -197,6 +199,8 @@ i18n:
 title: DevOps 连接器
 ```
 
+更多配置请参考[翻译配置](./usage/configuration#translate)
+
 ### 导出 PDF \{#export}
 
 :::warning
@@ -228,3 +232,22 @@ Options:
 ```dotenv title=".env.yarn"
 PLAYWRIGHT_DOWNLOAD_HOST="https://cdn.npmmirror.com/binaries/playwright"
 ```
+
+### 文档检查 \{#lint}
+
+```sh
+doom lint -h
+
+# output
+Usage: doom lint [options] [root]
+
+Lint the documentation
+
+Arguments:
+  root        Root directory of the documentation
+
+Options:
+  -h, --help  display help for command
+```
+
+更多配置请参考[文档检查配置](./usage/configuration#lint)

docs/zh/usage/configuration.md

@@ -208,3 +208,10 @@ translate:
 ```yaml
 editRepoBaseUrl: alauda/doom/tree/main/docs # https://github.com/ 前缀可以省略，仅当启用 `-R, --edit-repo` 命令行标志符时生效
 ```
+
+## 文档检查配置 \{#lint}
+
+```yaml
+lint:
+  cspellOptions: # 可选，cspell 配置项，参考 https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-eslint-plugin#options
+```

package.json

@@ -75,6 +75,7 @@
     "eslint-plugin-mdx": "^3.4.2",
     "html-tag-names": "^2.1.0",
     "mdast-util-mdx": "^2.0.1",
+    "mdast-util-mdx-jsx": "^2.1.4",
     "mermaid": "^11.6.0",
     "openai": "^5.0.0-beta.0",
     "openapi-types": "^12.1.3",
@@ -88,6 +89,7 @@
     "remark-directive": "^2.0.1",
     "remark-frontmatter": "^4.0.1",
     "remark-gfm": "^3.0.1",
+    "remark-mdx": "^2.3.0",
     "remark-stringify": "^10.0.3",
     "shiki": "^3.4.2",
     "simple-git": "^3.27.0",

src/cli/helpers.ts

@@ -54,7 +54,8 @@ export const defaultGitHubUrl = (url: string) =>
 
 const parseTerms_ = async () => {
   const terms = await xfetch(
-    'https://gitlab-ce.alauda.cn/alauda-public/product-doc-guide/-/raw/main/terms.yaml',
+    process.env.RAW_TERMS_URL ||
+      'https://gitlab-ce.alauda.cn/alauda-public/product-doc-guide/-/raw/main/terms.yaml',
     { type: 'text' },
   )
   return parse(terms) as NormalizedTermItem[]

src/cli/lint.ts

@@ -2,6 +2,7 @@ import type { Options } from '@cspell/eslint-plugin'
 import cspellRecommended from '@cspell/eslint-plugin/recommended'
 import js from '@eslint/js'
 import react from '@eslint-react/eslint-plugin'
+import { logger } from '@rspress/shared/logger'
 import { Command } from 'commander'
 import { merge } from 'es-toolkit/compat'
 import { ESLint } from 'eslint'
@@ -37,7 +38,7 @@ export const lintCommand = new Command('lint')
           ],
         },
         {
-          files: ['**/docs/en/**/*.{js,jsx,md,mdx,ts,tsx}'],
+          files: ['**/en/**/*.{js,jsx,md,mdx,ts,tsx}'],
           extends: [cspellRecommended],
           rules: {
             '@cspell/spellchecker': [
@@ -83,15 +84,31 @@ export const lintCommand = new Command('lint')
       ]),
     })
 
+    logger.start('Linting...')
+
     const results = await eslint.lintFiles('**/*.{js,jsx,ts,tsx,md,mdx}')
 
-    if (!results.length) {
-      return
-    }
+    const { error, warning } = results.reduce(
+      (count, result) => ({
+        error: count.error + result.errorCount,
+        warning: count.warning + result.warningCount,
+      }),
+      { error: 0, warning: 0 },
+    )
 
-    process.exitCode = 1
+    logger.info(
+      `Linting completed with ${error} errors and ${warning} warnings`,
+    )
 
     const formatter = await eslint.loadFormatter('stylish')
 
-    process.stderr.write(await formatter.format(results))
+    const formatted = await formatter.format(results)
+
+    if (formatted) {
+      console.log(formatted)
+    }
+
+    if (error) {
+      process.exitCode = 1
+    }
   })