开始
目录
创建项目
首先，你可以通过以下命令创建一个新目录：
mkdir my-docs && cd my-docs
执行 npm init -y 来初始化一个项目。你可以使用 npm、yarn 或 pnpm 安装 doom:
npm install -D @alauda/doom typescript
然后通过如下命令创建文件:
# 创建 docs 目录，默认支持中英文双语
mkdir docs/en && echo '# Hello World' > docs/en/index.md
mkdir docs/zh && echo '# 你好世界' > docs/zh/index.md
在 package.json 中加上如下的脚本:
{
"scripts": {
"dev": "doom dev",
"build": "doom build",
"new": "doom new",
"serve": "doom serve",
"translate": "doom translate",
"export": "doom export"
}
}
然后初始化一个配置文件 doom.config.yml:
同时新建 tsconfig.json，内容如下：
{
"compilerOptions": {
"jsx": "react-jsx",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"noUnusedLocals": true,
"noUnusedParameters": true,
"resolveJsonModule": true,
"skipLibCheck": true,
"strict": true,
"target": "ESNext",
},
"mdx": {
"checkMdx": true,
},
}
最后创建 global.d.ts 文件，内容如下：
/// <reference types="@alauda/doom/runtime" />
这样你便可以在 .mdx 文件中类型安全地使用 doom 提供的全局组件了。
命令行工具
doom -h
# output
Usage: doom [options] [command]
Doctor Doom making docs.
Options:
-V, --version output the version number
-c, --config <config> Specify the path to the config file
-v <version> Specify the version of the documentation, can also be `unversioned` or `unversioned-x.y`
-b, --base <base> Override the base of the documentation
-p, --prefix <prefix> Specify the prefix of the documentation base
-f, --force [boolean] Force to
1. fetch latest reference remotes or scaffolding templates, otherwise use local cache
2. translate ignore hash equality check and original text (default: false)
-i, --ignore [boolean] Ignore internal routes (default: false)
-d, --download [boolean] Display download pdf link on nav bar (default: false)
-e, --export [boolean] Run or build in exporting PDF mode, `apis/**` and `*/apis/**` routes will be ignored automatically (default: false)
-I, --include <language...> Include **only** the specific language(s), `en ru` for example
-E, --exclude <language...> Include all languages except the specific language(s), `ru` for example
-o, --out-dir <path> Override the `outDir` defined in the config file or the default `dist/{base}/{version}`, the resulting path will be `dist/{outDir}/{version}`
-r, --redirect <enum> Whether to redirect to the locale closest to `navigator.language` when the user visits the site, could be `auto`, `never` or `only-default-lang` (default: "only-default-lang")
-R, --edit-repo [boolean|url|lang] Whether to enable or override the `editRepoBaseUrl` config feature, `https://github.com/` prefix could be omitted; if a language code is provided, all other languages will use the same repo but with the language code as sub-path (default: false)
-a, --algolia [boolean|alauda] Whether to enable or use the alauda (docs.alauda.io) preset for Algolia search (default: false)
-S, --site-url Whether to enable the siteUrl for sitemap generation (default: false)
-n, --no-open Do not open the browser after starting the server
--lang <language> Specify the language of the documentation
-h, --help display help for command
Commands:
dev [options] [root] Start the development server
build [root] Build the documentation
preview|serve [options] [root] Preview the built documentation
new [template] Generate scaffolding from templates
translate [options] [root] Translate the documentation
export [options] [root] Export the documentation as PDF, `apis/**` and `*/apis/**` routes will be ignored automatically
lint [options] [root] Lint the documentation
help [command] display help for command
更多配置请参考配置
启动开发服务
执行 yarn dev 启动开发服务，浏览器会自动打开文档首页
doom dev -h
# output
Usage: doom dev [options] [root]
Start the development server
Arguments:
root Root directory of the documentation
Options:
-H, --host [host] Dev server host name
-P, --port [port] Dev server port number
-l, --lazy [boolean] Whether to enable `lazyCompilation` which could improve the compilation performance (default: true)
--no-lazy Do not enable `lazyCompilation`
-h, --help display help for command
生产环境构建
执行 yarn build 构建生产环境代码，构建完成后会在 dist 目录生成静态文件
本地预览
执行 yarn serve 预览构建后的静态文件，注意如果使用了 -b, -p 参数构建，预览时也需要使用 -b, -p 参数
使用脚手架模板
执行 yarn new 使用脚手架模板生成项目、模块或文档
翻译文档
doom translate -h
# output
Usage: doom translate [options] [root]
Translate the documentation
Arguments:
root Root directory of the documentation
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 of source dirs/files to translate
-C, --copy [boolean] Wether to copy relative assets to the target directory instead of following links (default: false)
-h, --help display help for command
-g, --glob 参数必填，可以指定需要翻译的文件目录或路径，支持 glob 语法，注意参数值必须带引号否则会被命令行解析造成非预期行为。示例：
yarn translate -g abc xyz，将把 <root>/<source>/abc, <root>/<source>/xyz
目录下的所有文档翻译到 <root>/<target>/abc, <root>/<target>/xyz 目录下yarn translate -g '*' 将翻译 <root>/<source> 下的所有文档文件
-C, --copy 参数可选，是否在目标文件不存在时复制本地路径的资源文件到目标目录，默认为 false，即改变资源文件的引用路径为引用源路径。示例：
- 当启动此参数
/<source>/abc.jpg 翻译时将复制 <root>/public/<source>/abc.jpg 到 <root>/public/<target>/abc.jpg，并修改文档中的引用路径为 /<target>/abc.jpg<root>/<source>/abc.mdx 文档中的 ./assets/xyz.jpg 翻译时将复制 <root>/<source>/assets/xyz.jpg 到 <root>/<target>/assets/xyz.jpg，图片引用路径保持不变<root>/<source>/abc.mdx 文档中的 ./assets/<source>/xyz.jpg 翻译时将复制 <root>/<source>/assets/<source>/xyz.jpg 到 <root>/<target>/assets/<target>/xyz.jpg，并修改文档中的引用路径为 ./assets/<target>/xyz.jpg
- 当没有启用此参数：
/<source>/abc.jpg 翻译时如果 <root>/public/<target>/abc.jpg 已存在，将修改文档中的引用路径为 /<target>/abc.jpg，否则保持图片引用路径保持不变<root>/<source>/abc.mdx 文档中的 ./assets/<source>/xyz.jpg 翻译时，如果 <root>/<target>/assets/<target>/xyz.jpg 已存在，将修改文档中的引用路径为 ./assets/<target>/xyz.jpg，否则将修改为 ../<source>/assets/<target>/xyz.jpg
WARNING
特殊地，如果使用 -g '*' 进行全量翻译，将会对比 source 和 target 目录文件列表，除 internalRoutes 之外的不匹配的 target 文件将被自动删除
TIP
翻译功能须在本地配置 AZURE_OPENAI_API_KEY 环境变量，请联系各自团队 Leader 获取
文档中可以使用元数据控制翻译行为
i18n:
title:
en: DevOps Connectors
additionalPrompts: '此文中的 Connectors 是专有名词，不要翻译'
disableAutoTranslation: false
title: DevOps 连接器
更多配置请参考翻译配置
导出 PDF
WARNING
请在执行导出操作前先执行 yarn build 构建操作
doom export -h
# output
Usage: doom export [options] [root]
Export the documentation as PDF, `apis/**` and `*/apis/**` routes will be ignored automatically
Arguments:
root Root directory of the documentation
Options:
-H, --host [host] Serve host name
-P, --port [port] Serve port number (default: "4173")
-h, --help display help for command
执行 yarn export 导出文档为 PDF 文件，注意如果使用了 -b, -p 参数构建，导出时也需要使用 -b, -p 参数
导出功能依赖 playwright，流水线请使用 build-harbor.alauda.cn/frontend/playwright-runner:doom 作为依赖安装和文档构建的基础镜像，
本地可以设置如下环境变量加速下载：
.env.yarn
PLAYWRIGHT_DOWNLOAD_HOST="https://cdn.npmmirror.com/binaries/playwright"
除了全站统一导出完整 pdf 文档外，doom 还支持指定入口导出单个 pdf 文件，更多配置请参考文档导出配置
文档检查
doom lint -h
# output
Usage: doom lint [options] [root]
Lint the documentation
Arguments:
root Root directory of the documentation
Options:
-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 基于 ESLint 和 cspell，如果希望在编辑器中拥有更好的体验，可以安装相应的插件 ESLint / CSpell，然后创建相应的配置文件:
-
eslint.config.mjs:
import doom from '@alauda/doom/eslint'
export default doom(new URL('docs', import.meta.url))
-
cspell.config.mjs:
export { default } from '@alauda/doom/cspell'
同时我们约定当前工作目录（CWD）下 .cspell 文件夹用于存放 CSpell 的字典文件，例如你可以创建 .cspell/k8s.txt：
更多配置请参考文档检查配置
