Skip to main content

​
Configuration

Doom uses a flexible configuration system that supports both static YAML files and dynamic JavaScript/TypeScript configuration files.

​
Configuration Files

​
YAML Configuration

For most use cases, a static YAML configuration file is sufficient. Doom supports:
  • doom.config.yaml
  • doom.config.yml
lang: en
title: My Documentation
logoText: My Project
themeConfig:
  socialLinks:
    - icon: github
      mode: link
      content: https://github.com/your-org/your-repo

​
JavaScript/TypeScript Configuration

For advanced scenarios requiring dynamic configuration or custom Rspress plugins, use JS/TS configuration files:
  • .js, .ts, .mjs, .mts, .cjs, .cts
import { defineConfig } from '@alauda/doom/config'

export default defineConfig({
  lang: 'en',
  title: 'My Documentation',
  logoText: 'My Project',
  // Add custom configuration here
})
The defineConfig helper provides full TypeScript type assistance for your configuration.

​
Basic Configuration

​
lang
string
default:"en"
Default documentation language. Set to null or undefined if multilingual support is not needed.
Doom supports Chinese (zh) and English (en) by default. When configured, language-specific subdirectories are expected in your docs folder.
​
title
string
required
Documentation title displayed in the browser tab.
Logo image displayed in the top-left corner. Supports:
  • Image URLs
  • Absolute paths (relative to public directory)
  • Relative paths (relative to tool directory)
Defaults to the built-in Alauda logo.
​
logoText
string
Text displayed next to the logo in the navigation bar.
​
icon
string
Documentation favicon. Defaults to the same value as logo.
​
base
string
default:"/"
Base path for documentation deployment. Use when deploying to a non-root path.
base: product-docs
# Site will be available at: /product-docs/
​
outDir
string
default:"dist/{base}/{version}"
Build output directory. When specified, changes to dist/{outDir}/{version}.

​
API Documentation

Configure CRD and OpenAPI documentation generation: 
api:
  # CRD definition files (supports glob patterns)
  crds:
    - docs/shared/crds/*.yaml
  
  # OpenAPI definition files (supports glob patterns)
  openapis:
    - docs/shared/openapis/*.json
  
  # Extract resource definitions into separate reference pages
  references:
    v1alpha1.CodeQualityBranch: /apis/references/CodeQualityBranch#v1alpha1.CodeQualityBranch
    io.k8s.api.apps.v1.DaemonSet: /apis/references/DaemonSet#io.k8s.api.apps.v1.DaemonSet
  
  # Optional: API path prefix for gateway/proxy services
  pathPrefix: /apis
Both JSON and YAML files are supported for CRDs and OpenAPI definitions. All paths are relative to the directory containing doom.config.*.

​
Reference Documentation

Incorporate content from other documentation sources: 
reference:
  - repo: alauda-public/product-doc-guide  # Optional, defaults to current repo
    branch: main  # Optional
    publicBase: docs/public  # Optional, for remote static resources
    sources:
      - name: anchor  # Globally unique reference name
        path: docs/index.mdx#introduction
        ignoreHeading: false  # Optional
        frontmatterMode: merge  # Optional: ignore|merge|replace|remove
        processors:  # Optional
          - type: ejsTemplate
            data:
              variableName: value

​
Frontmatter Modes

Keep the current document’s frontmatter (default behavior).
sidebar:
  collapsed: false  # Whether sidebar groups are collapsed by default
For small documentation projects, consider setting collapsed: false for better discoverability.

​
Route Filtering

​
Internal Routes

Exclude internal documentation when building: 
internalRoutes:  # Ignored when CLI flag `-i, --ignore` is enabled
  - '*/internal/**'
  - '*/drafts/**'

​
Only Include Routes

Whitelist specific routes: 
onlyIncludeRoutes:  # Only these routes are included with `-i` flag
  - '*/public/**'
  - '*/guides/**'

internalRoutes:  # Can be combined to further exclude routes
  - '*/public/draft.mdx'

​
Syntax Highlighting

Customize code syntax highlighting with Shiki: 
shiki:
  theme: nord  # See https://shiki.style/themes
  langs:  # See https://shiki.style/languages
    - javascript
    - typescript
    - python
    - yaml
  # transformers: only available in JS/TS config
Unconfigured languages will trigger warnings and fall back to plaintext rendering.

​
Translation

Configure AI-powered translation settings: 
translate:
  systemPrompt: |  # EJS template for system prompt
    You are a professional technical documentation engineer...
    <%= sourceLang %>, <%= targetLang %>, <%= userPrompt %>
  
  userPrompt: |  # Optional user-defined prompt
    Follow our style guide for technical terms...

​
Export Configuration

Define PDF export scopes: 
export:
  - name: User Guide  # Optional, defaults to document title
    scope: '*/guides/**'  # Required, supports glob patterns
  
  - name: API Reference
    scope:
      - '*/api/**'
      - '*/reference/**'

​
Search Integration

Integrate Algolia search: 
algolia:
  appId: YOUR_APP_ID
  apiKey: YOUR_API_KEY
  indexName: your_index_name

siteUrl: https://docs.example.com  # Required for sitemap generation
Algolia search requires a custom theme. Enable it by creating theme/index.ts:
theme/index.ts
export * from '@alauda/doom/theme'
Enable “Edit this page” links: 
# GitHub repository (https://github.com/ prefix is optional)
editRepoBaseUrl: alauda/doom/tree/main/docs
Only effective when the CLI flag -R, --edit-repo is enabled.

​
Linting

Configure documentation linting: 
lint:
  cspellOptions:  # CSpell configuration
    language: en
    words:
      - customword
      - myterm

​
Sites Configuration

Define subsites for multi-site documentation: 
- name: connectors  # Globally unique
  base: /devops-connectors
  version: v1.1
  
  displayName:
    en: DevOps Connectors
    zh: DevOps 连接器
  
  # For pulling images during full site builds
  repo: https://github.com/AlaudaDevops/connectors-operator
  image: devops/connectors-docs

​
CLI Options

Override configuration via command-line: 
doom build \
  --base /docs \
  --version v2.0 \
  --ignore \
  --export

​
Complete Example

lang: en
title: Doom Documentation
logoText: Doom
base: /

themeConfig:
  socialLinks:
    - icon: github
      mode: link
      content: https://github.com/alauda/doom

api:
  crds:
    - docs/shared/crds/*.yaml
  openapis:
    - docs/shared/openapis/*.json

sidebar:
  collapsed: false

internalRoutes:
  - '*/internal/**'

editRepoBaseUrl: alauda/doom/blob/main/docs

algolia:
  appId: USO7A9NBAD
  apiKey: 44896d7bbb41e9c1e807699d1dbb7cee
  indexName: doom_js_org

siteUrl: https://doom.js.org

export:
  - name: usage
    scope: '*/usage/*'

Build docs developers (and LLMs) love

Get started for freeTalk to us