feat: better integration with editor (#96)

JounQin · web-flow · commit 189cf9e7d99e · 2025-06-23T18:18:34.000+08:00
diff --git a/.changeset/wicked-beds-teach.md b/.changeset/wicked-beds-teach.md
@@ -0,0 +1,5 @@
+---
+"@alauda/doom": minor
+---
+
+feat: better integration with editor
diff --git a/.cspell/devops.txt b/.cspell/devops.txt
@@ -0,0 +1,9 @@
+katanomi
+tekton
+tektonchains
+tektonconfigs
+tektonhubs
+tektoninstallersets
+tektonpipelines
+tektonresults
+tektontriggers
diff --git a/.cspell/k8s.txt b/.cspell/k8s.txt
@@ -0,0 +1 @@
+openshiftpipelinesascodes
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -36,7 +36,9 @@ jobs:
         run: yarn --immutable
 
       - name: Build and Lint
-        run: yarn run-p build docs lint typecov
+        run: |
+          yarn build
+          yarn run-p docs lint typecov
         env:
           PARSER_NO_WATCH: true
           RAW_TERMS_URL: ${{ secrets.RAW_TERMS_URL }}
diff --git a/.github/workflows/pkg-pr-new.yml b/.github/workflows/pkg-pr-new.yml
@@ -32,4 +32,4 @@ jobs:
         run: yarn build
 
       - name: Publish
-        run: yarn dlx pkg-pr-new publish --compact
+        run: yarn dlx pkg-pr-new publish --compact --packageManager=yarn
diff --git a/cspell.config.js b/cspell.config.js
@@ -0,0 +1 @@
+export { default } from '@alauda/doom/cspell'
diff --git a/docs/en/start.mdx b/docs/en/start.mdx
@@ -1,5 +1,5 @@
 ---
-sourceSHA: c3feb38cb30b2f92c125dfa6af05ca6f5e9a23fd299bbbd39f4726159b7d7079
+sourceSHA: b7fe69a866c3e8893f7eddf6720d3366865e8e03b58658225bdd926ad71d6c87
 ---
 
 # Getting Started \{#start}
@@ -12,7 +12,7 @@ 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 install doom using npm, yarn, or pnpm:
+Run `npm init -y` to initialize a project. You can use npm, yarn, or pnpm to install doom:
 
 <PackageManagerTabs command="install -D @alauda/doom typescript" />
 
@@ -24,7 +24,7 @@ mkdir docs/en && echo '# Hello World' > docs/en/index.md
 mkdir docs/zh && echo '# 你好世界' > docs/zh/index.md
 ```
 
-Add the following scripts to your `package.json`:
+Add the following scripts to `package.json`:
 
 ```json
 {
@@ -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}
 
@@ -175,24 +175,24 @@ Options:
   -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 command line parsing. Examples:
+- 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:
   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 documents 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 path to the source path. Examples:
+  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`, `<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. In `<root>/<source>/abc.mdx`, the `./assets/xyz.jpg` reference 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`, the `./assets/<source>/xyz.jpg` reference will copy `<root>/<source>/assets/<source>/xyz.jpg` to `<root>/<target>/assets/<target>/xyz.jpg`, and the reference path in the document will be changed to `./assets/<target>/xyz.jpg`.
+    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. In `<root>/<source>/abc.mdx`, if `<root>/<target>/assets/<target>/xyz.jpg` exists, the reference path `./assets/<source>/xyz.jpg` will be changed to `./assets/<target>/xyz.jpg`; otherwise, it will be changed to `../<source>/assets/<target>/xyz.jpg`.
+    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`.
 
 :::warning
-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.
+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 the local environment variable `AZURE_OPENAI_API_KEY` to be configured. Please contact your team leader to obtain it.
+The translation feature requires configuring the `AZURE_OPENAI_API_KEY` environment variable locally. 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 the `yarn build` command before exporting.
+Please run `yarn build` before executing the export operation.
 :::
 
 ```sh
@@ -231,9 +231,9 @@ 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:
+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:
 
 ```dotenv title=".env.yarn"
 PLAYWRIGHT_DOWNLOAD_HOST="https://cdn.npmmirror.com/binaries/playwright"
@@ -256,4 +256,27 @@ Options:
   -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:
+
+- `eslint.config.mjs`:
+
+  ```js
+  import doom from '@alauda/doom/eslint'
+
+  export default await doom(new URL('docs', import.meta.url))
+  ```
+
+- `cspell.config.mjs`:
+
+  ```js
+  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`:
+
+```txt
+k8s
+kubernetes
+```
+
 For more configuration, please refer to [Lint Configuration](./usage/configuration#lint)
diff --git a/docs/zh/start.mdx b/docs/zh/start.mdx
@@ -254,4 +254,27 @@ Options:
   -h, --help  display help for command
 ```
 
+`doom lint` 基于 [`ESLint`](https://eslint.org/) 和 [`cspell`](https://cspell.org/)，如果希望在编辑器中拥有更好的体验，可以安装相应的插件 [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) / [CSpell](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)，然后创建相应的配置文件:
+
+- `eslint.config.mjs`:
+
+  ```js
+  import doom from '@alauda/doom/eslint'
+
+  export default await doom(new URL('docs', import.meta.url))
+  ```
+
+- `cspell.config.mjs`:
+
+  ```js
+  export { default } from '@alauda/doom/cspell'
+  ```
+
+同时我们约定当前工作目录（`CWD`）下 `.cspell` 文件夹用于存放 CSpell 的字典文件，例如你可以创建 `.cspell/k8s.txt`：
+
+```txt
+k8s
+kubernetes
+```
+
 更多配置请参考[文档检查配置](./usage/configuration#lint)
diff --git a/doom.config.yml b/doom.config.yml
@@ -26,11 +26,6 @@ reference:
 sidebar:
   collapsed: false
 editRepoBaseUrl: alauda/doom/tree/main/docs
-lint:
-  cspellOptions:
-    cspell:
-      words:
-        - katanomi
 algolia:
   appId: USO7A9NBAD
   apiKey: 44896d7bbb41e9c1e807699d1dbb7cee
diff --git a/eslint.config.js b/eslint.config.js
@@ -7,10 +7,13 @@ import { importX } from 'eslint-plugin-import-x'
 import * as reactHooks from 'eslint-plugin-react-hooks'
 import { config, configs } from 'typescript-eslint'
 
+import doom from '@alauda/doom/eslint'
+
 export default config(
   {
-    ignores: ['.yarn', 'dist', 'lib', 'node_modules', 'test', 'pyodide'],
+    ignores: ['pyodide'],
   },
+  ...(await doom(new URL('docs', import.meta.url))),
   eslint.configs.recommended,
   importX.flatConfigs.recommended,
   importX.flatConfigs.typescript,
@@ -37,6 +40,12 @@ export default config(
       ],
     },
   },
+  {
+    files: ['**/*.mdx'],
+    rules: {
+      'react-hooks/rules-of-hooks': 'off',
+    },
+  },
   {
     settings: {
       'import-x/resolver-next': createTypeScriptImportResolver(),
diff --git a/fixture-docs/en/test/managedtap.mdx b/fixture-docs/en/test/managedtap.mdx
@@ -0,0 +1,59 @@
+# Configuring Virtual Machines to Use Network Binding Mode for IPv6 Support
+
+The network binding mode is a plugin extension mechanism for virtual machine networking. By default, the platform uses a plugin called ManagedTap to enable IPv6 support for virtual machines. This plugin allows virtual machines to obtain IP addresses through the CNI's DHCP Server. Therefore, as long as the CNI's DHCP Server supports IPv6, virtual machines will also gain IPv6 capabilities.
+
+Currently, we use Kube-OVN as the CNI. Since Kube-OVN's DHCP Server has full IPv6 support, virtual machines can achieve robust IPv6 functionality through the combination of ManagedTap and Kube-OVN.
+
+## Prerequisites
+
+- ACP version must be v4.0.0 or higher.
+- Kube-OVN is used as the CNI, and the virtual machine subnet is configured as Underlay.
+
+## Procedure
+
+<Steps>
+
+### Add IPv6 Configuration to the Virtual Machine Subnet
+
+    ```bash
+    kubectl edit subnet <subnet-name>
+    ```
+
+    Add the following parameters under `spec`:
+
+    ```yaml
+    spec:
+      enableDHCP: true
+      enableIPv6RA: true
+      u2oInterconnection: true
+    ```
+
+### Create a Virtual Machine Using Network Binding Mode in the web console
+
+    When creating a virtual machine, select **Network Binding** as the network mode.
+
+### Access the Virtual Machine via VNC and Configure the Network Interface
+
+    For CentOS systems, edit the `/etc/sysconfig/network-scripts/ifcfg-enp1s0` file and add the following configuration:
+
+    ```bash
+    IPV6INIT=yes
+    DHCPV6C=yes
+    IPV6_AUTOCONF=yes
+    ```
+
+    restart network
+
+    ```bash
+    systemctl restart network
+    ```
+
+### Configure IPv6 Default Route
+
+    If the switch is configured to send Router Advertisement (RA) messages, manual route configuration is not required. The default route can be automatically learned through RA messages from the switch.
+
+    ```bash
+    ip r r default via <subnet-v6-gateway>
+    ```
+
+</Steps>
diff --git a/package.json b/package.json
@@ -14,6 +14,8 @@
   "exports": {
     "./package.json": "./package.json",
     "./config": "./lib/config.js",
+    "./cspell": "./lib/cspell.js",
+    "./eslint": "./lib/eslint.js",
     "./runtime": "./lib/runtime/index.js",
     "./theme": "./lib/theme.js",
     "./types": "./lib/types.js"
@@ -79,6 +81,7 @@
     "es-toolkit": "^1.39.3",
     "eslint": "^9.29.0",
     "eslint-plugin-mdx": "^3.5.0",
+    "globals": "^16.2.0",
     "html-tag-names": "^2.1.0",
     "mdast-util-mdx": "^3.0.0",
     "mdast-util-mdx-jsx": "^3.2.0",
diff --git a/src/cli/lint.ts b/src/cli/lint.ts
@@ -1,17 +1,10 @@
-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'
-import * as mdx from 'eslint-plugin-mdx'
-import tseslint from 'typescript-eslint'
 
+import doom from '../eslint.js'
 import type { GlobalCliOptions } from '../types.js'
 
-import { parseTerms } from './helpers.js'
 import { loadConfig } from './load-config.js'
 
 export const lintCommand = new Command('lint')
@@ -24,65 +17,11 @@ export const lintCommand = new Command('lint')
 
     const docsDir = config.root!
 
-    const parsedTerms = await parseTerms()
-
     const eslint = new ESLint({
       cwd: docsDir,
       overrideConfigFile: true,
       // @ts-expect-error -- stronger types
-      overrideConfig: tseslint.config([
-        {
-          extends: [
-            js.configs.recommended,
-            react.configs.recommended,
-            mdx.configs.flat,
-          ],
-        },
-        {
-          files: ['**/en/**/*.{js,jsx,md,mdx,ts,tsx}'],
-          extends: [cspellRecommended],
-          rules: {
-            '@cspell/spellchecker': [
-              'error',
-              merge(
-                {
-                  autoFix: true,
-                  cspell: {
-                    allowCompoundWords: true,
-                    words: parsedTerms.map((it) => it.en),
-                    flagWords: parsedTerms.flatMap(
-                      ({ badCases }) => badCases?.en ?? [],
-                    ),
-                  },
-                } satisfies Partial<Options>,
-                config.lint?.cspellOptions,
-              ),
-            ],
-          },
-        },
-        {
-          files: ['**/*.{ts,tsx}'],
-          extends: [
-            tseslint.configs.recommendedTypeChecked,
-            react.configs['recommended-typescript'],
-          ],
-          rules: {
-            '@typescript-eslint/no-misused-promises': 'off',
-            '@typescript-eslint/no-non-null-assertion': 'off',
-            '@typescript-eslint/restrict-template-expressions': [
-              'error',
-              { allowNumber: true },
-            ],
-            'prefer-const': ['error', { destructuring: 'all' }],
-          },
-          languageOptions: {
-            parser: tseslint.parser,
-            parserOptions: {
-              projectService: true,
-            },
-          },
-        },
-      ]),
+      overrideConfig: await doom(config.lint?.cspellOptions),
     })
 
     logger.start('Linting...')
diff --git a/src/cli/load-config.ts b/src/cli/load-config.ts
diff --git a/src/cspell.ts b/src/cspell.ts
diff --git a/src/eslint.ts b/src/eslint.ts
diff --git a/yarn.lock b/yarn.lock

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@alauda/doom": minor
 +---
++
 +feat: better integration with editor
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+export { default } from '@alauda/doom/cspell'`