Skip to main content

​
Customizing Your Documentation

Doom provides extensive customization options through configuration files, frontmatter, and code. This guide covers how to tailor your documentation site to match your brand and requirements.

​
Configuration File

All customization starts with your configuration file. Doom supports both YAML and JavaScript/TypeScript formats.

​
YAML Configuration

For most use cases, a static YAML file is sufficient:
doom.config.yml
title: My Documentation
lang: en
logo: /logo.svg
logoText: My Company
icon: /favicon.svg
base: /
YAML config supports doom.config.yaml or doom.config.yml filenames.

​
JavaScript/TypeScript Configuration

For dynamic configuration or custom plugins, use a JS/TS config file:
doom.config.ts
import { defineConfig } from '@alauda/doom/config'

export default defineConfig({
  title: 'My Documentation',
  lang: 'en',
  logo: '/logo.svg',
  logoText: 'My Company',
  // Add custom rspress plugins
  plugins: [
    // Your custom plugins here
  ]
})
Supported formats: .js/.ts/.mjs/.mts/.cjs/.cts
Use the defineConfig helper for TypeScript type assistance and autocompletion.

​
Basic Branding

1

Add your logo

Place your logo file in the docs/public/ directory:
docs/
└── public/
    ├── logo.svg
    ├── logo-dark.svg
    └── favicon.svg
Configure it in doom.config.yml:
logo: /logo.svg
icon: /favicon.svg
logoText: My Product
2

Customize the title

Set the browser tab title and logo text:
title: My Documentation Site
logoText: My Docs
The title appears in browser tabs, while logoText appears next to your logo in the navigation bar.
3

Configure base path

If deploying to a subdirectory, set the base path:
base: /product-docs
Your site will be accessible at https://example.com/product-docs

​
Language Configuration

​
Multilingual Setup

Doom supports bilingual documentation by default: 
lang: en  # Default language: 'en' or 'zh'
Set to null or undefined to disable multilingual support: 
lang: null  # Single language mode

​
Organizing Multilingual Content

docs/
├── en/
│   ├── index.md
│   └── guide.md
├── zh/
│   ├── index.md
│   └── guide.md
└── public/
    ├── en/
    │   └── images/
    └── zh/
        └── images/
Directory structure must be identical across languages to ensure proper link resolution.

​
Collapse Behavior

Control whether sidebar groups are collapsed by default: 
sidebar:
  collapsed: false  # Default: true
For documentation with fewer pages, setting collapsed: false improves discoverability.

​
Auto-Generated Sidebar

The sidebar is automatically generated from your file structure. Control the order using frontmatter: 
---
title: Getting Started
weight: 1
---
Lower weight values appear first. The index.md file always appears first in its group.

​
Page-Level Customization

Use frontmatter to customize individual pages: 
---
title: Custom Page Title
description: This appears in search results and meta tags
weight: 10
author: John Doe
category: Guides
---

# Page Content

​
Available Frontmatter Fields

​
title
string
Page title displayed in navigation and browser tab
​
description
string
Page description for SEO and search results
​
weight
number
Sort order (lower values appear first)
​
author
string
Document author name
​
category
string
Document category for organization

​
Syntax Highlighting

Customize code block appearance using Shiki: 
shiki:
  theme: github-dark
  langs:
    - javascript
    - typescript
    - bash
    - yaml
  # transformers only available in JS/TS config
Unconfigured languages trigger warnings and fall back to plaintext rendering.

​
Supported Themes

See Shiki themes for available options:
  • github-light
  • github-dark
  • dracula
  • nord
  • material-theme
Enable “Edit this page” links to your source repository: 
editRepoBaseUrl: alauda/doom/tree/main/docs
The https://github.com/ prefix can be omitted.
This feature is only active when the -R, --edit-repo CLI flag is enabled.
You can configure different repositories per language using the CLI: 
doom dev -R en  # Use 'en' subdirectory for other languages

​
Search Configuration

Integrate Algolia for powerful search: 
algolia:
  appId: YOUR_APP_ID
  apiKey: YOUR_API_KEY
  indexName: your-index
You need to create a custom theme to use Algolia. Create theme/index.ts:
export * from '@alauda/doom/theme'
Enable with the CLI flag: 
doom build -a

​
Robots.txt for Crawlers

Create docs/public/robots.txt for search engine crawlers: 
User-agent: *
Allow: /

Sitemap: https://docs.example.com/sitemap.xml

​
Dynamic Mount Configuration

Override configuration at runtime using overrides.yaml:
overrides.yaml
title:
  en: Custom Title - English
  zh: 自定义标题 - 中文
logoText:
  en: Product Name
  zh: 产品名称
This is useful for:
  • Multi-tenant deployments
  • Environment-specific branding
  • Version-specific customization
Place overrides.yaml alongside your built documentation: 
dist/
├── 4.0/
│   └── index.html
├── 4.1/
│   └── index.html
├── overrides.yaml
└── versions.yaml

​
Custom Components

Create reusable custom components in the shared directory:
docs/shared/CustomBanner.tsx
export const CustomBanner = ({ message }: { message: string }) => {
  return (
    <div style={{ 
      padding: '1rem', 
      background: '#f0f9ff',
      borderLeft: '4px solid #3b82f6'
    }}>
      {message}
    </div>
  )
}
Use in your MDX pages:
docs/en/guide.mdx
import { CustomBanner } from '../shared/CustomBanner'

# My Guide

<CustomBanner message="Welcome to our documentation!" />

​
Internationalization for Components

For multilingual component content, use the i18n system:
1

Create i18n.json

Define translations in docs/i18n.json:
{
  "banner.welcome": {
    "en": "Welcome to our documentation",
    "zh": "欢迎访问我们的文档"
  }
}
2

Use in components

Import and use the useI18n hook:
import { useI18n } from '@rspress/core/runtime'

export const WelcomeBanner = () => {
  const t = useI18n()
  return <div>{t('banner.welcome')}</div>
}
3

Use in MDX

Call the hook inline:
import { useI18n } from '@rspress/core/runtime'

# {useI18n()('banner.welcome')}

​
Output Directory

Customize the build output location: 
outDir: custom-dist
Default: dist/{base}/{version}
With outDir: dist/{outDir}/{version} Or use the CLI flag: 
doom build -o custom-output

​
Advanced Configuration

​
Internal Routes

Exclude internal documentation from public builds: 
internalRoutes:
  - '*/internal/**'
  - '*/drafts/**'
Enable filtering with: 
doom build -i  # Ignore internal routes

​
Only Include Routes

Build only specific routes: 
onlyIncludeRoutes:
  - '*/public/**'
  - '*/guides/**'
internalRoutes:
  - '*/public/internal/**'  # Further exclude within included routes

​
API Path Prefix

Configure API documentation URL prefix: 
api:
  pathPrefix: /apis
Useful when using gateway or proxy services.

​
Theme Customization

For advanced theming, create a custom theme:
theme/index.ts
import { Layout, usePageData } from '@rspress/core/theme'
export * from '@alauda/doom/theme'

export default {
  Layout() {
    const pageData = usePageData()
    return (
      <>
        <Layout />
        <div className="custom-footer">
          © 2024 My Company
        </div>
      </>
    )
  }
}
See the Rspress custom theme guide for more details.

​
Next Steps

Project Structure

Learn about file organization conventions

Deployment

Deploy your customized documentation

Plugins

Extend functionality with plugins

API Documentation

Configure API documentation features

Build docs developers (and LLMs) love

Get started for freeTalk to us