#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 install -D @alauda/doom typescript

Then create files with the following commands:

# Create docs directories, default supports bilingual Chinese and English
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

Also create 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 allows you to safely 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]   Whether to enable or override the `editRepoBaseUrl` config feature, `https://github.com/` prefix could be omitted (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
  -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 [root]                     Lint the documentation
  help [command]                  display help for command

For more configuration, please refer to Configuration

#Starting the Development Server

Run yarn dev to start the development server; the browser will automatically open the documentation homepage.

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 building, static files will be generated in the dist directory.

#Local Preview

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.

#Using Scaffolding Templates

Run yarn new to generate projects, modules, or documentation using scaffolding templates.

#Translating 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 for source dirs/files
  -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 directories or paths of files to translate, supporting glob syntax. Note that the parameter value must be quoted to avoid unexpected behavior from the command line parser. 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 document files 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 paths to the source paths. Examples:
  • When this parameter is enabled:
    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. 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.
    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.
  • 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, 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.

You can control translation behavior in the document metadata:

i18n:
  title:
    en: DevOps Connectors
  additionalPrompts: 'The term Connectors in this document is a proper noun and should not be translated'
  disableAutoTranslation: false
title: DevOps Connectors

For more configuration, please refer to Translation Configuration

#Exporting PDF

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 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.

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

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

Besides exporting a unified full-site PDF, doom also supports exporting a single PDF file for a specified entry. For more configuration, please refer to 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:
  -h, --help  display help for command

doom lint is based on ESLint and cspell. For a better experience in your editor, you can install the corresponding plugins ESLint / CSpell, 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'

We also conventionally use the .cspell folder under the current working directory (CWD) to store CSpell dictionary files. For example, you can create .cspell/k8s.txt:

k8s
kubernetes

For more configuration, please refer to Documentation Linting Configuration