Project Structure

Doom follows a convention-based approach to documentation structure, automatically generating navigation and features based on your file organization.

Directory Layout

A typical Doom documentation project has the following structure:

my-docs/
├── docs/
│   ├── en/                    # English documentation
│   │   ├── index.mdx          # Homepage
│   │   ├── getting-started.md
│   │   └── guides/
│   │       ├── index.mdx      # Guides section homepage
│   │       ├── installation.md
│   │       └── configuration.md
│   ├── zh/                    # Chinese documentation
│   │   ├── index.mdx
│   │   └── guides/
│   │       └── ...
│   ├── shared/                # Shared components & content
│   │   ├── CommonContent.mdx
│   │   └── Button.tsx
│   └── public/                # Static assets
│       ├── en/
│       │   └── images/
│       ├── zh/
│       │   └── images/
│       └── favicon.ico
├── doom.config.yml            # Main configuration
├── sites.yaml                 # Multi-site configuration (optional)
└── theme/                     # Custom theme (optional)
    └── index.ts

Directory Conventions

Documentation Root (`docs/`)

The docs/ directory contains all documentation content and is structured based on your language configuration.

Multilingual
Single Language

With lang: en in your config:

docs/
├── en/  # English content
└── zh/  # Chinese content

Each language directory must have an identical structure to ensure consistent routing.

With lang: null in your config:

docs/
├── index.mdx
├── guides/
└── api/

No language subdirectories are created.

Index Files

Index files serve special purposes in Doom’s navigation system:

Root Index

The index.mdx or index.md file at the root of your language directory becomes the homepage:

docs/en/index.mdx  → Homepage (/)

Section Index

Index files in subdirectories define navigation groups:

guides/index.mdx

# Guides

This is the guides section homepage.

The first-level heading becomes the sidebar group title.

Auto-generated Overview

Use the <Overview /> component to automatically list all pages in a section:

guides/index.mdx

# Guides

<Overview />

This generates a card-based layout showing page titles, descriptions, and headings.

Shared Directory (`docs/shared/`)

Store reusable components and content that shouldn’t generate navigation entries:

docs/shared/
├── components/
│   ├── Button.tsx          # React components
│   └── StatusBadge.tsx
├── content/
│   ├── CommonNote.mdx      # Reusable content snippets
│   └── Prerequisites.mdx
└── utils/
    └── helpers.ts          # Utility functions

Files in the shared/ directory are excluded from automatic route generation.

Public Directory (`docs/public/`)

Static assets served directly:

docs/public/
├── en/
│   └── images/
│       ├── architecture.png
│       └── screenshot.jpg
├── zh/
│   └── images/
│       └── ...
├── _remotes/              # Remote reference assets (gitignored)
├── favicon.ico
├── robots.txt
└── logo.svg

The public/_remotes/ directory stores assets from remote references and should be added to .gitignore:

.gitignore

docs/public/_remotes/

Reference assets using absolute paths from the public root:

File Naming Conventions

Supported Extensions

.md

Markdown

Standard Markdown files with GFM support

.mdx

MDX

Markdown with JSX components support

Naming Guidelines

Use kebab-case

Name files using lowercase with hyphens:

✅ getting-started.md
✅ api-reference.mdx
❌ GettingStarted.md
❌ api_reference.mdx

Be descriptive

Use clear, descriptive names that reflect content:

✅ installation-guide.md
✅ authentication-setup.mdx
❌ guide.md
❌ page1.mdx

Match across languages

Keep filenames identical across language directories:

docs/en/guides/installation.md
docs/zh/guides/installation.md

Doom automatically generates the sidebar based on your file structure.

Automatic Sorting

By default, files are sorted alphabetically by filename (excluding index.*):

guides/
├── index.mdx          # Always first
├── 01-introduction.md # Alphabetical
├── 02-setup.md
└── 03-advanced.md

Custom Sorting

Use the weight frontmatter property to control order:

---
title: Advanced Configuration
weight: 5  # Lower numbers appear first
---

Changes to navigation structure require a dev server restart to take effect.

Frontmatter

Doom uses YAML frontmatter for page metadata:

---
title: Page Title
description: Brief description for SEO and cards
author: Author Name
category: Category
weight: 1
---

title

string

Page title shown in navigation and browser tab. Falls back to the first H1 heading if not specified.

description

string

Brief page description used in overview cards and SEO meta tags.

weight

number

Sort order in navigation. Lower values appear first.

author

string

Content author name (optional).

Multi-site Structure

For complex documentation with multiple subsites, use sites.yaml:

sites.yaml

- name: main-docs
  base: /docs
  version: v2.0
  displayName:
    en: Main Documentation
    zh: 主文档

- name: connectors
  base: /connectors
  version: v1.1
  displayName:
    en: Connectors
    zh: 连接器
  repo: https://github.com/org/connectors
  image: org/connectors-docs

Reference external sites in your documentation:

<ExternalSite name="connectors" />
<ExternalSiteLink name="connectors" href="/setup" children="Setup Guide" />

API Documentation Structure

API documentation follows a specific organization:

docs/
├── en/
│   └── apis/
│       ├── index.mdx
│       ├── crds/                  # CRD documentation
│       │   ├── index.mdx
│       │   └── Resource.mdx
│       ├── references/            # API references
│       │   ├── index.mdx
│       │   └── Type.mdx
│       └── kubernetes_apis/       # K8s API docs
│           └── workload/
│               └── deployment.mdx
└── shared/
    ├── crds/                      # CRD YAML definitions
    │   └── *.yaml
    └── openapis/                  # OpenAPI specs
        └── *.json

Configure API documentation sources:

doom.config.yml

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

Custom Theme Structure

Override default theme behavior:

theme/
├── index.ts                # Theme entry point
├── components/
│   └── CustomNavbar.tsx
└── styles/
    └── custom.css

theme/index.ts

// Use default Doom theme with Algolia support
export * from '@alauda/doom/theme'

// Or customize
import { Layout } from '@rspress/theme'
import { CustomNavbar } from './components/CustomNavbar'

export default {
  ...Layout,
  Navbar: CustomNavbar,
}

Configuration Files

doom.config.yml

Main configuration file at the project root:

lang: en
title: My Documentation
logoText: MyProject
# ... other options

See the Configuration page for all options.

sites.yaml

Multi-site configuration (optional):

- name: site1
  base: /site1
  version: v1.0

i18n.json

Internationalization strings for components:

docs/i18n.json

{
  "welcome": {
    "en": "Welcome",
    "zh": "欢迎"
  }
}

Best Practices

Keep consistent structure

Mirror directory structure across all language versions
Use identical filenames in each language directory
Maintain the same navigation hierarchy

Organize by feature

guides/
├── authentication/
│   ├── index.mdx
│   ├── oauth.md
│   └── api-keys.md
└── deployment/
    ├── index.mdx
    ├── docker.md
    └── kubernetes.md

Use meaningful paths

URLs are generated from file paths:

docs/en/guides/authentication/oauth.md
→ /guides/authentication/oauth

Choose paths that make sense as URLs.

Leverage the shared directory

Extract common components to shared/components/
Store reusable content snippets in shared/content/
Keep data definitions in shared/data/

Migration Checklist

When organizing an existing documentation project:

Set up directory structure

Create the base directories:

mkdir -p docs/{en,zh,shared,public}

Organize content by language

Move existing content into language-specific directories:

mv existing-docs/* docs/en/

Create index files

Add index.mdx files for homepage and each section.

Add weight values to frontmatter for custom ordering.

Extract reusable components

Move shared components to docs/shared/.

Run doom dev and verify sidebar generation.

Get Started

Core Concepts

Features

Guides

Project Structure

Project Structure

Directory Layout

Directory Conventions

Documentation Root (`docs/`)

Index Files

Shared Directory (`docs/shared/`)

Public Directory (`docs/public/`)

File Naming Conventions

Supported Extensions

Naming Guidelines

Navigation Generation

Automatic Sorting

Custom Sorting

Frontmatter

Multi-site Structure

API Documentation Structure

Custom Theme Structure

Configuration Files

doom.config.yml

sites.yaml

i18n.json

Best Practices

Migration Checklist

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Guides

​Project Structure

​Directory Layout

​Directory Conventions

​Documentation Root (docs/)

​Index Files

​Shared Directory (docs/shared/)

​Public Directory (docs/public/)

​File Naming Conventions

​Supported Extensions

​Naming Guidelines

​Navigation Generation

​Automatic Sorting

​Custom Sorting

​Frontmatter

​Multi-site Structure

​API Documentation Structure

​Custom Theme Structure

​Configuration Files

​doom.config.yml

​sites.yaml

​i18n.json

​Best Practices

​Migration Checklist

Build docs developers (and LLMs) love

Project Structure

Directory Layout

Directory Conventions

Documentation Root (`docs/`)

Index Files

Shared Directory (`docs/shared/`)

Public Directory (`docs/public/`)

File Naming Conventions

Supported Extensions

Naming Guidelines

Navigation Generation

Automatic Sorting

Custom Sorting

Frontmatter

Multi-site Structure

API Documentation Structure

Custom Theme Structure

Configuration Files

doom.config.yml

sites.yaml

i18n.json

Best Practices

Migration Checklist