You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f3176ef
Browse filesBrowse the repository at this point in the historyBrowse files
@@ -45,7 +45,7 @@ Then initialize a configuration file `doom.config.yml`:
45
45
title: My Docs
46
46
```
47
47
48
-
Also create a `tsconfig.json` file with the following content:
48
+
At the same time, create a new `tsconfig.json` with the following content:
49
49
50
50
```jsonc
51
51
{
@@ -72,7 +72,7 @@ Finally, create a `global.d.ts` file with the following content:
72
72
/// <reference types="@alauda/doom/runtime" />
73
73
```
74
74
75
-
This allows you to use doom's global components in `.mdx` files with type safety.
75
+
This way, you can use the global components provided by doom in `.mdx` files with type safety.
76
76
77
77
## CLI Tool \{#cli}
78
78
@@ -118,11 +118,11 @@ Commands:
118
118
help [command] display help for command
119
119
```
120
120
121
-
For more configuration, please refer to [Configuration](./usage/configuration)
121
+
For more configuration, see [Configuration](./usage/configuration)
122
122
123
-
### Starting the Development Server \{#dev}
123
+
### Start the Development Server \{#dev}
124
124
125
-
Run `yarn dev` to start the development server, the browser will automatically open the documentation homepage.
125
+
Run `yarn dev` to start the development server, and the browser will automatically open the documentation home page
126
126
127
127
```sh
128
128
doom dev -h
@@ -145,17 +145,17 @@ Options:
145
145
146
146
### Production Build \{#build}
147
147
148
-
Run `yarn build` to build the production code. After building, static files will be generated in the `dist` directory.
148
+
Run `yarn build` to build the production code. After the build is complete, static files will be generated in the `dist` directory.
149
149
150
150
### Local Preview \{#serve}
151
151
152
-
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.
152
+
Run `yarn serve` to preview the built static files. Note that if you built with the `-b`, `-p` parameters, you also need to use the `-b`, `-p` parameters when previewing.
153
153
154
-
### Using Scaffolding Templates \{#new}
154
+
### Use Scaffold Templates \{#new}
155
155
156
-
Run `yarn new` to generate projects, modules, or documentation using scaffolding templates.
156
+
Run `yarn new` to generate a project, module, or documentation using scaffold templates.
157
157
158
-
### Translating Documentation \{#translate}
158
+
### Translate Documentation \{#translate}
159
159
160
160
```bash
161
161
doom translate -h
@@ -176,43 +176,44 @@ Options:
176
176
-h, --help display helpforcommand
177
177
```
178
178
179
-
- The `-g, --glob` parameter is required. You 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:
180
-
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.
181
-
2.`yarn translate -g '*'` will translate all documents under `<root>/<source>`.
182
-
- The `-C, --copy` parameter is optional. It controls whether to copy local resource files to the target directory when the target file does not exist. The default is `false`, which means changing the resource file reference path to the source path. Examples:
183
-
- When enabled:
184
-
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`.
185
-
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.
186
-
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`.
187
-
- When not enabled:
188
-
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.
189
-
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`.
179
+
- The `-g, --glob` parameter is required. You can specify the file directories or paths to translate. It supports `glob` syntax. Note that the parameter value must be enclosed in quotes, otherwise it will be parsed by the command line and may cause unexpected behavior. Examples:
180
+
1.`yarn translate -g abc xyz` will translate all documentation under the `<root>/<source>/abc` and `<root>/<source>/xyz`
181
+
directories to `<root>/<target>/abc` and `<root>/<target>/xyz`
182
+
2.`yarn translate -g '*'` will translate all documentation files under `<root>/<source>`
183
+
- The `-C, --copy` parameter is optional. It controls whether local asset files are copied to the target directory when the target file does not exist. The default is `false`, which means the reference path of the asset file is changed to point to the source path. Examples:
184
+
- When this parameter is enabled:
185
+
1. Translating `/<source>/abc.jpg` will copy `<root>/public/<source>/abc.jpg` to `<root>/public/<target>/abc.jpg`, and update the reference path in the document to `/<target>/abc.jpg`
186
+
2. Translating `./assets/xyz.jpg` in `<root>/<source>/abc.mdx` will copy `<root>/<source>/assets/xyz.jpg` to `<root>/<target>/assets/xyz.jpg`, and the image reference path remains unchanged
187
+
3. Translating `./assets/<source>/xyz.jpg` in `<root>/<source>/abc.mdx` will copy `<root>/<source>/assets/<source>/xyz.jpg` to `<root>/<target>/assets/<target>/xyz.jpg`, and update the reference path in the document to `./assets/<target>/xyz.jpg`
188
+
- When this parameter is not enabled:
189
+
1. When translating `/<source>/abc.jpg`, if `<root>/public/<target>/abc.jpg` already exists, the reference path in the document will be changed to `/<target>/abc.jpg`; otherwise, the image reference path remains unchanged
190
+
2. When translating `./assets/<source>/xyz.jpg` in `<root>/<source>/abc.mdx`, if `<root>/<target>/assets/<target>/xyz.jpg` already 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`
190
191
191
192
:::warning
192
-
Specially, 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.
193
+
In particular, if you use `-g '*'` for a full translation, the file lists in the `source` and `target` directories will be compared. Any mismatched`target` files except for `internalRoutes` will be deleted automatically.
193
194
:::
194
195
195
196
:::tip
196
-
The translation feature requires configuring the `AZURE_OPENAI_API_KEY`environment variable locally. Please contact your team leader to obtain it.
197
+
The translation feature requires the `ALAUDA_OPENAI_BASE_URL` and `ALAUDA_OPENAI_API_KEY`environment variables to be configured locally. Please contact your team Leader to obtain them.
197
198
:::
198
199
199
-
You can control translation behavior in the document metadata:
200
+
You can use metadata in the documentation to control translation behavior:
200
201
201
202
```yaml
202
203
i18n:
203
204
title:
204
205
en: DevOps Connectors
205
-
additionalPrompts: 'The term Connectors in this document is a proper noun and should not be translated'
206
+
additionalPrompts: '此文中的 Connectors 是专有名词,不要翻译'
206
207
disableAutoTranslation: false
207
-
title: DevOps Connectors
208
+
title: DevOps 连接器
208
209
```
209
210
210
-
For more configuration, please refer to [Translation Configuration](./usage/configuration#translate)
211
+
For more configuration, see [Translation Configuration](./usage/configuration#translate)
211
212
212
-
### Exporting PDF \{#export}
213
+
### Export PDF \{#export}
213
214
214
215
:::warning
215
-
Please run the `yarn build` command before exporting.
216
+
Please run `yarn build` before performing the export operation.
216
217
:::
217
218
218
219
```sh
@@ -232,15 +233,15 @@ Options:
232
233
-h, --help display help for command
233
234
```
234
235
235
-
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.
236
+
Run `yarn export` to export the documentation as a PDF file. Note that if you built with the `-b`, `-p` parameters, you also need to use the `-b`, `-p` parameters when exporting.
236
237
237
-
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:
238
+
The export feature depends on [`playwright`](https://playwright.dev). In pipelines, use `build-harbor.alauda.cn/frontend/playwright-runner:doom` as the base image for dependency installation and documentation builds. For local development, you can set the following environment variable to speed up downloads:
Besides exporting a complete PDF 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)
244
+
In addition to exporting a complete PDF document for the entire site, `doom` also supports exporting a single PDF file from a specified entry point. For more configuration, see[Documentation Export Configuration](./usage/configuration#export)
244
245
245
246
### Documentation Linting \{#lint}
246
247
@@ -261,7 +262,7 @@ Options:
261
262
-h, --help display helpforcommand
262
263
```
263
264
264
-
`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:
265
+
`doom lint` is based on [`ESLint`](https://eslint.org/) and [`cspell`](https://cspell.org/). If you want 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), and then create the corresponding configuration files:
265
266
266
267
-`eslint.config.mjs`:
267
268
@@ -277,11 +278,11 @@ Options:
277
278
export { default } from'@alauda/doom/cspell'
278
279
```
279
280
280
-
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`:
281
+
At the same time, we 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`:
281
282
282
283
```txt
283
284
k8s
284
285
kubernetes
285
286
```
286
287
287
-
For more configuration, please refer to [Lint Configuration](./usage/configuration#lint)
288
+
For more configuration, see [Documentation Linting Configuration](./usage/configuration#lint)
0 commit comments