Quick Start

This guide will help you create your first documentation site with Doom and explore its core features.

Make sure you’ve completed the Installation guide before proceeding.

Your First Documentation Page

Let’s create a simple documentation structure with multiple pages.

Start Development Server

First, start the development server to see changes in real-time:

npm run dev

Your documentation will be available at http://localhost:5173/

Create a Guide Section

Create a new section for guides:

mkdir -p docs/en/guide

Create an index file for the section at docs/en/guide/index.mdx:

docs/en/guide/index.mdx

---
title: Guide
description: Learn how to use our product
---

# Guide

Welcome to our comprehensive guide!

<Overview />

The <Overview /> component automatically displays all pages in the current section with their titles and descriptions.

Add Guide Pages

Create your first guide page at docs/en/guide/getting-started.md:

docs/en/guide/getting-started.md

---
title: Getting Started
description: Your first steps with our product
weight: 1
---

# Getting Started

This guide will help you get started quickly.

## Installation

Install our product using npm:

````bash
npm install @example/product
````

## Basic Usage

Here's a simple example:

````javascript
import { Product } from '@example/product'

const product = new Product()
product.start()
````

The weight property controls the order in the sidebar (lower numbers appear first).

Check Your Work

Save all files and check your browser. You should see:

A “Guide” section in the sidebar
An index page with overview
A “Getting Started” page

The sidebar is automatically generated from your file structure!

Understanding Directory Structure

Doom uses a convention-based approach to organize your documentation:

docs/
├── en/                     # English documentation
│   ├── index.mdx          # Homepage (required)
│   ├── guide/             # Guide section
│   │   ├── index.mdx      # Section overview
│   │   ├── getting-started.md
│   │   └── advanced.md
│   ├── api/               # API reference section
│   │   ├── index.mdx
│   │   └── endpoints.md
│   └── faq.md             # FAQ page at root level
├── zh/                     # Chinese documentation
│   └── ...                # Same structure
├── public/                 # Static assets
│   ├── en/
│   │   └── images/
│   └── zh/
│       └── images/
└── shared/                 # Shared components/data
    └── components/

Key Conventions

index files

index.md or index.mdx files become section homepages and group pages in the sidebar

Automatic Ordering

Pages are sorted alphabetically by filename. Use weight in frontmatter to customize order

Nested Sections

Create nested folders for sub-sections. Each folder can have its own index.mdx

Shared Directory

The shared/ directory is for reusable components and won’t generate pages

Using MDX and Components

Doom supports MDX, which lets you use React components in your Markdown files.

Built-in Components

Doom provides several built-in components:

Overview
PackageManagerTabs
Code Examples

Display all pages in a section:

# My Section

<Overview />

Show commands for different package managers:

<PackageManagerTabs command="install @example/package" />

Syntax highlighted code blocks:

````javascript title="app.js"
console.log('Hello, World!')
````

Example Page with Components

Create a feature-rich page at docs/en/guide/components.mdx:

docs/en/guide/components.mdx

---
title: Using Components
description: Learn how to use components in your documentation
weight: 2
---

# Using Components

Doom supports various ways to enhance your documentation.

## Installation Options

Choose your preferred package manager:

<PackageManagerTabs command="install @example/package" />

## Code Examples

Here's a TypeScript example with syntax highlighting:

````typescript title="example.ts"
interface User {
  name: string
  email: string
}

function greetUser(user: User): string {
  return `Hello, ${user.name}!`
}
````

## Image Support

Add images from the public directory:


## External Links

Reference external documentation:
- [Rspress Documentation](https://rspress.dev)
- [React Documentation](https://react.dev)

Working with Frontmatter

Frontmatter is metadata at the top of your Markdown files:

---
title: Page Title                    # Browser tab and sidebar
description: Page description         # Used in <Overview /> and SEO
weight: 1                            # Order in sidebar (lower = first)
author: John Doe                     # Optional metadata
category: Tutorial                   # Optional metadata
---

Special Frontmatter Fields

Translation
Weight
Source Hash

Control AI translation behavior:

---
title: My Page
i18n:
  additionalPrompts: "Keep 'MyProduct' untranslated"
  disableAutoTranslation: false
---

Control sidebar ordering:

---
title: Introduction
weight: 1
---

Lower weight = appears first

Automatically added by translation:

---
title: My Page
sourceSHA: a1b2c3d4...
---

Don’t edit this manually!

CLI Commands

Doom provides several commands for different workflows:

Development

npm run dev

# Custom port
npm run dev -- -P 3000

# Custom host
npm run dev -- -H 0.0.0.0

Content Creation

# Generate new page from template
npm run new

# Lint documentation
npm run lint

# Lint specific files
npm run lint -- -g "docs/en/guide/**"

Translation

Translation requires the AZURE_OPENAI_API_KEY environment variable. Contact your team administrator to obtain it.

# Translate specific directories
npm run translate -- -g "guide" "api" -s en -t zh

# Translate all content
npm run translate -- -g "*" -s en -t zh

# Copy assets instead of linking
npm run translate -- -g "guide" -s en -t zh -C

Export

# Export to PDF (build first!)
npm run build
npm run export

Configuration Basics

Your doom.config.yml controls the site’s behavior. Here are essential options:

doom.config.yml

# Language settings
lang: en                    # Default language

# Site metadata
title: My Documentation      # Browser title
logoText: My Docs           # Logo text in navbar
icon: /favicon.ico          # Favicon path

# Navigation
themeConfig:
  socialLinks:
    - icon: github
      mode: link
      content: https://github.com/username/repo

# Sidebar behavior
sidebar:
  collapsed: false          # Keep sidebar expanded by default

# Base path (for subdirectory deployment)
base: /docs                 # Site will be at domain.com/docs

# Output directory
outDir: dist                # Build output directory

For advanced configuration, see the Configuration Documentation.

API Documentation

Doom has first-class support for API documentation.

OpenAPI/Swagger

Add OpenAPI Spec

Place your OpenAPI spec file in docs/shared/openapis/:

mkdir -p docs/shared/openapis
# Add your api.json or api.yaml file

Configure

Update doom.config.yml:

api:
  openapis:
    - docs/shared/openapis/api.json
  pathPrefix: /api/v1

Create API Page

Create docs/en/api/users.mdx:

# User Management API

<OpenAPIPath path="/users" />

Kubernetes CRDs

Add CRD Files

Place CRD YAML files in docs/shared/crds/:

mkdir -p docs/shared/crds
# Add your CRD files

Configure

Update doom.config.yml:

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

Create CRD Page

Create docs/en/api/custom-resource.mdx:

# Custom Resource

<K8sAPI name="customresources.example.io" />

For more details, see the API Documentation Guide.

Multi-language Support

Doom makes it easy to maintain documentation in multiple languages.

Manual Translation

Create the same file structure in each language directory:

docs/
├── en/
│   └── guide/
│       └── setup.md
└── zh/
    └── guide/
        └── setup.md

Doom automatically:
- Generates language switcher
- Routes users to correct language
- Maintains navigation structure

AI Translation

Set API Key

Add Azure OpenAI API key to your environment:

export AZURE_OPENAI_API_KEY="your-api-key"

Translate Content

Run the translate command:

npm run translate -- -g "guide" -s en -t zh

Review & Edit

Check the translated files in docs/zh/guide/ and make any necessary adjustments.

The AI translation uses GPT-4 and understands technical terms, code blocks, and Markdown formatting. It won’t translate code examples or component names.

Building and Deployment

Build for Production

# Standard build
npm run build

# Output: dist/

Multi-Version Builds

# Build version 2.0
npm run build -- -v 2.0
# Output: dist/2.0/

# Build version 1.5
npm run build -- -v 1.5
# Output: dist/1.5/

# Both versions are now accessible

Create a versions.yaml file in your output directory:

versions.yaml

- '2.0'
- '1.5'

Preview Production Build

npm run serve

Deploy to Static Hosting

The dist directory contains static files. Deploy to:

GitHub Pages
Vercel
Netlify

.github/workflows/deploy.yml

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm install
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

vercel.json

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}

netlify.toml

[build]
  command = "npm run build"
  publish = "dist"

Next Steps

Configuration

Learn about all configuration options

Markdown & MDX

Master content creation with Markdown

Convention

Understand Doom’s conventions

Deployment

Advanced deployment strategies

API Documentation

Generate API reference docs

Translation

Internationalization features

Tips and Best Practices

Organize content logically

Group related pages in folders
Use descriptive folder and file names
Keep the hierarchy shallow (2-3 levels max)
Use index.mdx files for section overviews

Write clear frontmatter

Always include title and description
Use weight to order important pages first
Keep descriptions under 160 characters for SEO

Optimize images

Store images in public/{language}/images/
Use descriptive filenames
Optimize image size (use WebP when possible)
Always include alt text

Use MDX features wisely

Import components only when needed
Keep custom components in docs/shared/components/
Test components work after build
Use built-in components when possible

Maintain translation consistency

Keep file structures identical across languages
Use translation terms configuration for consistent terminology
Review AI translations before committing
Update all languages when making structural changes

Need Help? Check out the full documentation or visit the GitHub repository for more examples and community support.

Get Started

Core Concepts

Features

Guides

​Quick Start

​Your First Documentation Page

​Understanding Directory Structure

​Key Conventions

index files

Automatic Ordering

Nested Sections

Shared Directory

​Using MDX and Components

​Built-in Components

​Example Page with Components

​Working with Frontmatter

​Special Frontmatter Fields

​CLI Commands

​Development

​Content Creation

​Translation

​Export

​Configuration Basics

​API Documentation

​OpenAPI/Swagger

​Kubernetes CRDs

​Multi-language Support

​Manual Translation

​AI Translation

​Building and Deployment

​Build for Production

​Multi-Version Builds

​Preview Production Build

​Deploy to Static Hosting

​Next Steps

Configuration

Markdown & MDX

Convention

Deployment

API Documentation

Translation

​Tips and Best Practices

Build docs developers (and LLMs) love

Quick Start

Your First Documentation Page

Understanding Directory Structure

Key Conventions

Using MDX and Components

Built-in Components

Example Page with Components

Working with Frontmatter

Special Frontmatter Fields

CLI Commands

Development

Content Creation

Translation

Export

Configuration Basics

API Documentation

OpenAPI/Swagger

Kubernetes CRDs

Multi-language Support

Manual Translation

AI Translation

Building and Deployment

Build for Production

Multi-Version Builds

Preview Production Build

Deploy to Static Hosting

Next Steps

Tips and Best Practices