Markdown & MDX

Doom supports both standard Markdown and MDX (Markdown + JSX) for writing documentation. This allows you to create rich, interactive documentation with reusable components.

Markdown Support

Doom supports the full GitHub Flavored Markdown (GFM) specification, plus additional extensions.

Code Callouts

Annotate code with numbered callouts to explain specific lines:

```sh
Memory overhead per virtual machine ≈ (1.002 × requested memory) \
              + 218 MiB \  # [!code callout]
              + 8 MiB × (number of vCPUs) \  # [!code callout]
              + 16 MiB × (number of graphics devices) \  # [!code callout]
              + (additional memory overhead) # [!code callout]
```

:::callouts
1. Required for the processes that run in the `virt-launcher` pod.
2. Number of virtual CPUs requested by the virtual machine.
3. Number of virtual graphics cards requested by the virtual machine.
4. Additional memory overhead:
   - If your environment includes an SR-IOV network device or GPU, allocate 1 GiB per device.
   - If SEV is enabled, add 256 MiB.
   - If TPM is enabled, add 53 MiB.
:::

Tips for using callouts:

Use inline code comments appropriate to the language (;, #, //, /* */, --, )
To treat [!code callout] as a literal comment, escape it with [\!code callout]
If :::callouts displays incorrectly due to nesting, use <div class="doom-callouts"> or the <Callouts> component instead

Mermaid Diagrams

Create diagrams using Mermaid syntax:

```mermaid
graph TD;
    A[Start] -->|Success| B[Build]
    A -->|Failure| C[Error]
    B -->|Test| D[Deploy]
    C -->|Retry| A
    D --> E[Complete]
```

Mermaid in VSCode

Install the Markdown Preview Mermaid extension for real-time preview in VSCode.

Container Directives

Use custom containers for callouts:

:::note
This is a note container.
:::

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

:::warning
Be careful with this configuration.
:::

:::danger
This action is irreversible!
:::

:::info
Additional context goes here.
:::

MDX Overview

MDX extends Markdown with JSX syntax, enabling interactive components and dynamic content. See the Rspress MDX guide for complete details.

Using MDX Files

Create files with the .mdx extension to use JSX components:

example.mdx

---
title: Example Page
---

import { Button } from './components/Button'

# My Interactive Page

Here's a button component:

<Button onClick={() => alert('Clicked!')}>Click me</Button>

Built-in Components

Doom provides global components that work without imports in .mdx files.

Rspress Components

The following Rspress built-in components are available globally:

Badge
Card/LinkCard
Tabs
Steps

Display badges for status, version, or labels:

<Badge type="info">v1.0</Badge>
<Badge type="success">Stable</Badge>
<Badge type="warning">Beta</Badge>
<Badge type="danger">Deprecated</Badge>

Create clickable cards:

<Card title="Quick Start" href="/getting-started">
  Get up and running in 5 minutes.
</Card>

<LinkCard href="/api" title="API Reference" description="Complete API documentation" />

Organize content in tabs:

<Tabs>
  <Tab title="npm">
    ````bash
    npm install @alauda/doom
    ````
  </Tab>
  <Tab title="yarn">
    ````bash
    yarn add @alauda/doom
    ````
  </Tab>
</Tabs>

Display numbered steps:

<Steps>
  ### Install dependencies
  Run `npm install` to install required packages.
  
  ### Configure the project
  Create a `doom.config.yml` file in your project root.
  
  ### Run development server
  Execute `doom dev` to start the local server.
</Steps>

Doom Components

Doom provides specialized components for documentation:

Overview

Display a table of contents for the current section:

index.mdx

# Getting Started

<Overview />

This automatically generates a list of pages in the current directory with their titles and descriptions.

Directive

An alternative to container syntax, useful for nested content:

<Directive type="warning" title="Important">
  Make sure to backup your data before proceeding.
</Directive>

<Directive type="tip" title="Pro Tip">
  Use keyboard shortcuts to speed up your workflow.
</Directive>

type

string

required

Container type: note, tip, info, warning, danger

title

string

Custom title for the directive container

ExternalSite

Reference external documentation sites:

<ExternalSite name="connectors" />

Requires configuration in sites.yaml.

ExternalSiteLink

Create links to external sites:

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

In MDX, using the children prop vs. child elements has different rendering:

{/* Renders inline */}
<ExternalSiteLink name="site" href="/link" children="Text" />

{/* Renders in a paragraph */}
<ExternalSiteLink name="site" href="/link">
  Text
</ExternalSiteLink>

Term

Insert dynamic terminology:

<Term name="company" textCase="capitalize" />
<Term name="product" textCase="lower" />
<Term name="productShort" textCase="upper" />

name

string

required

Built-in term name from your terminology configuration

textCase

'lower' | 'upper' | 'capitalize'

Text transformation to apply

TermsTable

Display a table of all defined terms:

<TermsTable />

JsonViewer

Render JSON data with syntax highlighting:

<JsonViewer value={{ 
  name: 'Doom',
  version: '1.0.0',
  features: ['MDX', 'API Docs', 'PDF Export']
}} />

PackageManagerTabs

Quickly show commands for different package managers:

<PackageManagerTabs command="install @alauda/doom" />

Automatically generates tabs for npm, yarn, and pnpm.

Custom Components

Create reusable components in the shared directory:

shared/CommonContent.tsx

import { usePageData } from '@rspress/core/runtime'

export const CommonContent = () => {
  const { page } = usePageData()
  return (
    <div className="common-content">
      <h2>{page.title}</h2>
      <p>Page path: {page.routePath}</p>
    </div>
  )
}

Import and use in MDX files:

content.mdx

import { CommonContent } from '../shared/CommonContent'

# My Page

<CommonContent />

Components exported from .mdx files cannot accept props. Use .tsx components when you need to pass props.See this issue for more details.

Internationalization in Components

Use the useI18n hook for multilingual components:

Define translations

docs/i18n.json

{
  "welcome": {
    "zh": "欢迎",
    "en": "Welcome"
  },
  "description": {
    "zh": "这是描述",
    "en": "This is a description"
  }
}

Use in React components

shared/Welcome.tsx

import { useI18n } from '@rspress/core/runtime'

export const Welcome = () => {
  const t = useI18n()
  return <h1>{t('welcome')}</h1>
}

Use in MDX files

welcome.mdx

import { useI18n } from '@rspress/core/runtime'

# {useI18n()('welcome')}

{useI18n()('description')}

Best Practices

When to use Markdown vs MDX

Use Markdown (.md) for simple, static content
Use MDX (.mdx) when you need:
- Interactive components
- Dynamic content
- Component reuse
- Access to runtime APIs

Component organization

Store reusable components in docs/shared/
Use .tsx for components that need props
Use .mdx for simple content snippets
Keep API-related components separate from content components

Performance tips

Avoid heavy client-side logic in MDX components
Use static content when possible
Lazy load large components
Minimize the number of imported dependencies

Get Started

Core Concepts

Features

Guides

Markdown & MDX

Markdown & MDX

Markdown Support

Code Callouts

Mermaid Diagrams

Container Directives

MDX Overview

Using MDX Files

Built-in Components

Rspress Components

Doom Components

Overview

Directive

ExternalSite

ExternalSiteLink

Term

TermsTable

JsonViewer

PackageManagerTabs

Custom Components

Internationalization in Components

Define translations

Use in React components

Use in MDX files

Best Practices

Further Reading

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Guides

​Markdown & MDX

​Markdown Support

​Code Callouts

​Mermaid Diagrams

​Container Directives

​MDX Overview

​Using MDX Files

​Built-in Components

​Rspress Components

​Doom Components

​Overview

​Directive

​ExternalSite

​ExternalSiteLink

​Term

​TermsTable

​JsonViewer

​PackageManagerTabs

​Custom Components

​Internationalization in Components

​Define translations

​Use in React components

​Use in MDX files

​Best Practices

​Further Reading

Build docs developers (and LLMs) love

Markdown & MDX

Markdown Support

Code Callouts

Mermaid Diagrams

Container Directives

MDX Overview

Using MDX Files

Built-in Components

Rspress Components

Doom Components

Overview

Directive

ExternalSite

ExternalSiteLink

Term

TermsTable

JsonViewer

PackageManagerTabs

Custom Components

Internationalization in Components

Define translations

Use in React components

Use in MDX files

Best Practices

Further Reading