Plugins

Doom is built on Rspress and provides a rich plugin ecosystem to extend functionality. In addition to the built-in Auto Sidebar and API plugins, Doom includes several other plugins for enhanced documentation features.

Built-in Plugins

Doom includes these plugins out of the box:

Auto Sidebar

Automatically generate navigation from directory structure

API Documentation

Generate docs from OpenAPI specs and Kubernetes CRDs

Auto TOC

Automatically generate table of contents for pages

Directives

Support for special MDX directives and callouts

Global Components

Mermaid

Render Mermaid diagrams directly in documentation

Permission

Document and validate permission requirements

Replace

Find and replace content during build

Shiki

Advanced syntax highlighting with Shiki

Auto TOC Plugin

Automatically generates a table of contents based on page headings.

Usage

import { autoTocPlugin } from '@alauda/doom/plugins'
import { defineConfig } from '@rspress/core'

export default defineConfig({
  plugins: [autoTocPlugin()]
})

The plugin adds a remark plugin that processes markdown headings and generates navigation structure.

Configuration

Control TOC generation using frontmatter:

---
title: My Page
toc: false              # Disable TOC for this page
overviewHeaders: [2, 3] # Include only H2 and H3 in TOC
---

Directives Plugin

Supports custom MDX directives for callouts and special content blocks.

Usage

import { directivesPlugin } from '@alauda/doom/plugins'
import { defineConfig } from '@rspress/core'

export default defineConfig({
  plugins: [directivesPlugin()]
})

Supported Directives

The plugin enables special directive syntax:

:::note
This is a note callout
:::

:::warning
This is a warning
:::

:::tip
This is a helpful tip
:::

:::danger
This is critical information
:::

Global Components Plugin

Registers components to be available globally across all MDX files without imports.

Usage

import { globalPlugin } from '@alauda/doom/plugins'
import { defineConfig } from '@rspress/core'

export default defineConfig({
  plugins: [
    globalPlugin({
      components: {
        MyComponent: './src/components/MyComponent',
        AnotherComponent: './src/components/Another'
      }
    })
  ]
})

Example

Once registered, use components without imports:

<!-- No import needed! -->
<MyComponent title="Hello" />

<AnotherComponent>
  Content here
</AnotherComponent>

Mermaid Plugin

Renders Mermaid diagrams for flowcharts, sequence diagrams, and more.

Usage

import { mermaidPlugin } from '@alauda/doom/plugins'
import { defineConfig } from '@rspress/core'

export default defineConfig({
  plugins: [mermaidPlugin()]
})

Creating Diagrams

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do Something]
    B -->|No| D[Do Something Else]
    C --> E[End]
    D --> E
```

Permission Plugin

Documents permission requirements and validates role-based access configurations.

Configuration

# doom.config.yml
permission:
  functionresources:
    - docs/shared/functionresources/*.yaml
  roletemplates:
    - docs/shared/roletemplates/*.yaml

Usage

Define function resources:

# functionresources/admin-functions.yaml
apiVersion: v1
kind: FunctionResource
metadata:
  name: admin-panel
spec:
  description: "Access to admin panel"
  permissions:
    - read
    - write
    - delete

Define role templates:

# roletemplates/admin-role.yaml
apiVersion: v1
kind: RoleTemplate
metadata:
  name: admin
spec:
  displayName: "Administrator"
  resources:
    - functionresource: admin-panel
      permissions: [read, write, delete]

Components

Use in documentation:

<PermissionTable resource="admin-panel" />

<RoleMatrix role="admin" />

Replace Plugin

Find and replace content during the build process.

Usage

import { replacePlugin } from '@alauda/doom/plugins'
import { defineConfig } from '@rspress/core'

export default defineConfig({
  plugins: [
    replacePlugin({
      replacements: [
        {
          from: /VERSION/g,
          to: '1.0.0'
        },
        {
          from: '{{COMPANY}}',
          to: 'Acme Corp'
        }
      ]
    })
  ]
})

Example

Source markdown:

# Version VERSION Released

{{COMPANY}} is proud to announce version VERSION.

Built output:

# Version 1.0.0 Released

Acme Corp is proud to announce version 1.0.0.

Shiki Plugin

Provides advanced syntax highlighting using Shiki.

Features

Multiple Themes: Support for light and dark themes
Wide Language Support: Hundreds of languages
Custom Grammars: Add custom language definitions
Line Highlighting: Highlight specific lines
Line Numbers: Optional line number display

Usage

import { shikiPlugin } from '@alauda/doom/plugins'
import { defineConfig } from '@rspress/core'

export default defineConfig({
  plugins: [
    shikiPlugin({
      themes: {
        light: 'github-light',
        dark: 'github-dark'
      },
      languages: ['typescript', 'javascript', 'python', 'rust']
    })
  ]
})

Code Examples

// TypeScript with Shiki highlighting
interface User {
  id: string
  name: string
  email: string
}

function getUser(id: string): Promise<User> {
  return fetch(`/api/users/${id}`)
    .then(res => res.json())
}

Creating Custom Plugins

Doom plugins follow the Rspress plugin API:

import type { RspressPlugin } from '@rspress/core'

export const myCustomPlugin = (options = {}): RspressPlugin => {
  return {
    name: 'my-custom-plugin',
    
    // Lifecycle hooks
    async config(config) {
      // Modify config
      return config
    },
    
    async addRuntimeModules(config, isProd) {
      // Add virtual modules
      return {
        'my-virtual-module': `export default ${JSON.stringify(data)}`
      }
    },
    
    async beforeBuild(config, isProd) {
      // Run before build
    },
    
    async afterBuild(config, isProd) {
      // Run after build
    },
    
    // Markdown processing
    markdown: {
      remarkPlugins: [
        // Add remark plugins
      ],
      rehypePlugins: [
        // Add rehype plugins
      ]
    },
    
    // Build config
    builderConfig: {
      // Modify Rsbuild config
    }
  }
}

Plugin API

name

string

required

Unique plugin identifier

config

function

Modify the user configuration

async config(config: UserConfig, utils: ConfigUtils): Promise<UserConfig>

addRuntimeModules

function

Add virtual modules available at runtime

async addRuntimeModules(
  config: UserConfig,
  isProd: boolean
): Promise<Record<string, string>>

beforeBuild

function

Hook called before build starts

async beforeBuild(config: UserConfig, isProd: boolean): Promise<void>

afterBuild

function

Hook called after build completes

async afterBuild(config: UserConfig, isProd: boolean): Promise<void>

markdown

object

Configure markdown processing

{
  remarkPlugins: Plugin[],
  rehypePlugins: Plugin[]
}

builderConfig

object

Modify Rsbuild configuration

Example Custom Plugin

import type { RspressPlugin } from '@rspress/core'
import { visit } from 'unist-util-visit'

// Plugin to add reading time to pages
export const readingTimePlugin = (): RspressPlugin => {
  return {
    name: 'reading-time-plugin',
    
    markdown: {
      remarkPlugins: [
        () => (tree, file) => {
          let wordCount = 0
          
          visit(tree, 'text', (node) => {
            wordCount += node.value.split(/\s+/).length
          })
          
          const readingTime = Math.ceil(wordCount / 200) // 200 WPM
          
          // Add to frontmatter
          file.data.frontmatter = file.data.frontmatter || {}
          file.data.frontmatter.readingTime = readingTime
        }
      ]
    },
    
    async addRuntimeModules() {
      return {
        'reading-time-component': `
          export function ReadingTime({ minutes }) {
            return <div>Reading time: {minutes} min</div>
          }
        `
      }
    }
  }
}

Plugin Configuration

Add plugins in your Doom config:

import { defineConfig } from '@rspress/core'
import { 
  autoSidebarPlugin,
  apiPlugin,
  mermaidPlugin,
  shikiPlugin
} from '@alauda/doom'

export default defineConfig({
  plugins: [
    autoSidebarPlugin({ collapsed: false }),
    apiPlugin({ localBasePath: './docs' }),
    mermaidPlugin(),
    shikiPlugin({
      themes: {
        light: 'github-light',
        dark: 'github-dark'
      }
    })
  ]
})

Best Practices

Use Built-in Plugins

Leverage Doom’s built-in plugins before creating custom ones.

Keep Plugins Focused

Each plugin should handle a single responsibility.

Handle Errors Gracefully

Always include error handling and helpful error messages.

Document Configuration

Provide clear documentation for plugin options and usage.

Test Thoroughly

Test plugins with various content types and edge cases.

Performance Matters

Optimize plugin performance, especially for large sites.

Plugin Examples

Check the Doom source code for real-world plugin implementations:

~/workspace/source/packages/doom/src/plugins/auto-sidebar/ - Auto Sidebar
~/workspace/source/packages/doom/src/plugins/api/ - API Documentation
~/workspace/source/packages/doom/src/plugins/mermaid/ - Mermaid Diagrams
~/workspace/source/packages/doom/src/plugins/directives/ - MDX Directives

Auto Sidebar

Navigation generation plugin

API Documentation

API documentation plugin

Translation

AI-powered translation

Get Started

Core Concepts

Features

Guides

​Plugins

​Built-in Plugins

Auto Sidebar

API Documentation

Auto TOC

Directives

Global Components

Mermaid

Permission

Replace

Shiki

​Auto TOC Plugin

​Usage

​Configuration

​Directives Plugin

​Usage

​Supported Directives

​Global Components Plugin

​Usage

​Example

​Mermaid Plugin

​Usage

​Creating Diagrams

​Permission Plugin

​Configuration

​Usage

​Components

​Replace Plugin

​Usage

​Example

​Shiki Plugin

​Features

​Usage

​Code Examples

​Creating Custom Plugins

​Plugin API

​Example Custom Plugin

​Plugin Configuration

​Best Practices

Use Built-in Plugins

Keep Plugins Focused

Handle Errors Gracefully

Document Configuration

Test Thoroughly

Performance Matters

​Plugin Examples

​Related Features

Auto Sidebar

API Documentation

Translation

Build docs developers (and LLMs) love

Plugins

Built-in Plugins

Auto TOC Plugin

Usage

Configuration

Directives Plugin

Usage

Supported Directives

Global Components Plugin

Usage

Example

Mermaid Plugin

Usage

Creating Diagrams

Permission Plugin

Configuration

Usage

Components

Replace Plugin

Usage

Example

Shiki Plugin

Features

Usage

Code Examples

Creating Custom Plugins

Plugin API

Example Custom Plugin

Plugin Configuration

Best Practices

Plugin Examples

Related Features