Getting Started

Creating a Project

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 use npm, yarn, or pnpm to install doom:

npm

yarn

pnpm

bun

deno

npm install -D @alauda/doom typescript

Then create the files with the following commands:

# Create the docs directory, bilingual support for Chinese and English is enabled by default
mkdir docs/en && echo '# Hello World' > docs/en/index.md
mkdir docs/zh && echo '# 你好世界' > docs/zh/index.md

Add the following scripts to package.json:

{
  "scripts": {
    "dev": "doom dev",
    "build": "doom build",
    "new": "doom new",
    "serve": "doom serve",
    "translate": "doom translate",
    "export": "doom export"
  }
}

Then initialize a configuration file doom.config.yml:

title: My Docs

At the same time, create a new tsconfig.json with the following content:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "strict": true,
    "target": "ESNext",
  },
  "mdx": {
    "checkMdx": true,
  },
}

Finally, create a global.d.ts file with the following content:

/// <reference types="@alauda/doom/runtime" />

This way, you can use the global components provided by doom in .mdx files with type safety.

CLI Tool

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

For more configuration, see Configuration

Start the Development Server

Run yarn dev to start the development server, and the browser will automatically open the documentation home page

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

Production Build

Run yarn build to build the production code. After the build is complete, static files will be generated in the dist directory.

Local Preview

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.

Use Scaffold Templates

Run yarn new to generate a project, module, or documentation using scaffold templates.

Translate Documentation

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]     Whether to copy relative assets to the target directory instead of following links (default: false)
  -h, --help               display help for command

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:
1. yarn translate -g abc xyz will translate all documentation under the <root>/<source>/abc and <root>/<source>/xyz directories to <root>/<target>/abc and <root>/<target>/xyz
2. yarn translate -g '*' will translate all documentation files under <root>/<source>
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:
- When this parameter is enabled:
  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
  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
  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
- When this parameter is not enabled:
  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
  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

WARNING

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.

TIP

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.

You can use metadata in the documentation to control translation behavior:

i18n:
  title:
    en: DevOps Connectors
  additionalPrompts: '此文中的 Connectors 是专有名词，不要翻译'
  disableAutoTranslation: false
title: DevOps 连接器

For more configuration, see Translation Configuration

Export PDF

WARNING

Please run yarn build before performing the export operation.

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

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.

The export feature depends on playwright. 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:

.env.yarn

PLAYWRIGHT_DOWNLOAD_HOST="https://cdn.npmmirror.com/binaries/playwright"

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

Documentation Linting

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 is based on ESLint and cspell. If you want a better experience in your editor, you can install the corresponding plugins ESLint / CSpell, and then create the corresponding configuration files:

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'

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:

k8s
kubernetes

For more configuration, see Documentation Linting Configuration

#Getting Started

#TOC

#Creating a Project

#CLI Tool

#Start the Development Server

#Production Build

#Local Preview

#Use Scaffold Templates

#Translate Documentation

#Export PDF

#Documentation Linting