Skip to main content

​
Installation

This guide will walk you through installing Doom and setting up your first documentation project.

​
Prerequisites

Before you begin, ensure you have the following installed on your system:
  • Node.js: Version 20.19.0 or higher
  • Package Manager: npm, yarn, or pnpm
  • Text Editor: VS Code, WebStorm, or your preferred editor

​
Check Node.js Version

Verify your Node.js version: 
node --version
If you need to upgrade Node.js, visit nodejs.org or use a version manager like nvm: 
# Using nvm
nvm install 20.19.0
nvm use 20.19.0

​
Installation Methods

​
Method 1: Create a New Project

1

Create Project Directory

First, create a new directory for your documentation project:
mkdir my-docs
cd my-docs
2

Initialize Package

Initialize a new npm package:
npm init -y
This creates a package.json file with default values.
3

Install Doom

Install Doom and TypeScript as development dependencies:
npm install -D @alauda/doom typescript

​
Method 2: Add to Existing Project

If you have an existing project, simply install Doom: 
npm install --save-dev @alauda/doom typescript

​
Project Setup

1

Create Documentation Structure

Set up the basic documentation directory structure. Doom supports multiple languages by default:
# Create English documentation
mkdir -p docs/en
echo '# Hello World' > docs/en/index.md

# Create Chinese documentation
mkdir -p docs/zh
echo '# 你好世界' > docs/zh/index.md

# Create public directory for static assets
mkdir -p docs/public/en
mkdir -p docs/public/zh
The en and zh directories represent English and Chinese languages. You can add more languages like ru for Russian.
2

Configure Package Scripts

Add Doom commands to your package.json:
package.json
{
  "scripts": {
    "dev": "doom dev",
    "build": "doom build",
    "serve": "doom serve",
    "new": "doom new",
    "translate": "doom translate",
    "export": "doom export",
    "lint": "doom lint"
  }
}
These scripts provide:
  • dev: Start development server with hot reload
  • build: Build production-ready static files
  • serve: Preview the built documentation
  • new: Generate new pages from templates
  • translate: AI-powered translation between languages
  • export: Export documentation to PDF
  • lint: Check documentation quality with ESLint and CSpell
3

Create Configuration File

Create a doom.config.yml file in your project root:
doom.config.yml
lang: en
title: My Documentation
logoText: My Docs
themeConfig:
  socialLinks:
    - icon: github
      mode: link
      content: https://github.com/yourusername/your-repo
This minimal configuration sets:
  • Default language to English
  • Site title for browser tabs
  • Logo text in the navigation bar
  • GitHub link in the header
4

Configure TypeScript

Create a tsconfig.json file for TypeScript support:
tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "strict": true,
    "target": "ESNext"
  },
  "mdx": {
    "checkMdx": true
  }
}
This enables:
  • JSX support for React components
  • Modern module resolution
  • Strict type checking
  • MDX file type checking
5

Add Type Definitions

Create a global.d.ts file for Doom’s global types:
global.d.ts
/// <reference types="@alauda/doom/runtime" />
This provides type definitions for:
  • Global components like <Overview />, <PackageManagerTabs />
  • MDX components and utilities
  • Doom runtime APIs

​
Project Structure

After setup, your project should look like this: 
my-docs/
├── docs/
│   ├── en/
│   │   └── index.md
│   ├── zh/
│   │   └── index.md
│   └── public/
│       ├── en/
│       └── zh/
├── doom.config.yml
├── global.d.ts
├── package.json
└── tsconfig.json

​
Optional Configuration

​
Editor Setup (VS Code)

For the best development experience in VS Code, install these extensions:
  1. ESLint - JavaScript/TypeScript linting
  2. CSpell - Spell checker
  3. MDX - Syntax highlighting for MDX files
Create .vscode/extensions.json: 
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "streetsidesoftware.code-spell-checker",
    "unifiedjs.vscode-mdx"
  ]
}

​
Linting Setup

For editor integration of linting tools:
1

ESLint Configuration

Create eslint.config.mjs:
eslint.config.mjs
import doom from '@alauda/doom/eslint'

export default doom(new URL('docs', import.meta.url))
2

CSpell Configuration

Create cspell.config.mjs:
cspell.config.mjs
export { default } from '@alauda/doom/cspell'
3

Custom Dictionary

Create .cspell/custom.txt for project-specific terms:
.cspell/custom.txt
Doom
Rspress
Alauda

​
Git Setup

Create a .gitignore file:
.gitignore
# Dependencies
node_modules/

# Build output
dist/
.doom/

# Environment files
.env
.env.local

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Remote references (generated)
docs/public/_remotes/

​
Verify Installation

Test your installation by starting the development server: 
npm run dev
You should see output similar to: 
  > Local:    http://localhost:5173/
  > Network:  http://192.168.1.100:5173/
Open the local URL in your browser to see your documentation site.

​
Troubleshooting

If you see an error about Node version:
error @alauda/[email protected]: The engine "node" is incompatible with this module.
Upgrade your Node.js to version 20.19.0 or higher:
nvm install 20.19.0
nvm use 20.19.0
If port 5173 is already in use, specify a different port:
doom dev -P 3000
Make sure you have created the global.d.ts file with Doom’s type reference:
/// <reference types="@alauda/doom/runtime" />
Restart your TypeScript server in VS Code: Cmd+Shift+P → “TypeScript: Restart TS Server”
PDF export requires Playwright browsers. Install them:
npx playwright install
For faster downloads in China, set the download mirror:
PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright npx playwright install

​
Next Steps

Quick Start

Learn the basics and create your first documentation pages

Configuration

Explore all configuration options for Doom

Markdown Guide

Learn how to write content with Markdown and MDX

API Documentation

Generate API docs from OpenAPI specs and CRDs
Pro Tip: Use doom new to generate documentation pages from templates. This helps maintain consistency across your documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us