How the Docs System Works

Behind the Scenes

This page explains how the OpenClaw documentation system works internally. It is intended for contributors who want to add or update documentation, and for anyone curious about the technical implementation.

Markdown Files

All documentation is written as Markdown files stored in the repository under:

content/openclaw/docs/
├── en/              # English documentation
│   ├── getting-started/
│   ├── channels/
│   ├── billing/
│   ├── advanced/
│   ├── security/
│   ├── troubleshooting/
│   └── meta/
└── de/              # German documentation
    ├── getting-started/
    ├── channels/
    ├── billing/
    ├── advanced/
    ├── security/
    ├── troubleshooting/
    └── meta/

Each documentation page exists as two files: one in en/ and one in de/. Both versions must have the same slug and category.

YAML Frontmatter

Every Markdown file starts with a YAML frontmatter block that defines metadata:

---
title: Page Title
slug: page-slug
category: getting-started
section: Getting Started
position: 3
---

Category and Section Mapping

Document Sync Process

Documentation files are synced to the database through the DocumentSyncService. This service:

1. Scans the content/openclaw/docs/ directory for Markdown files
2. Parses YAML frontmatter from each file
3. Converts Markdown content to HTML
4. Calculates an estimated reading time
5. Generates a vector embedding for semantic search
6. Stores everything in the oc_document_embeddings table

The Sync Flow

Markdown file on disk
  → DocumentSyncService reads the file
  → YAML frontmatter parsed for metadata
  → Markdown body converted to HTML
  → Reading time calculated from word count
  → Text sent to embedding API (4096 dimensions)
  → Record upserted in oc_document_embeddings table

Database Record Fields

Each synced document creates a record with:

Semantic Search with pgvector

The documentation system uses PostgreSQL's pgvector extension to enable semantic search. When a user asks a question, the system:

1. Converts the question into a vector embedding using the same embedding model
2. Queries the oc_document_embeddings table using vector similarity search
3. Returns the most relevant documentation pages ranked by similarity

This means users can find documentation by describing what they are looking for in natural language, rather than needing to know exact keywords or page titles.

How Vector Search Differs from Text Search

Text search finds exact or fuzzy word matches. Searching for "server won't start" would only find pages containing those specific words.

Vector search understands meaning. Searching for "server won't start" would also find pages about "instance not running" or "deployment failure" because the concepts are semantically similar.

Linking Between Pages

Documentation pages link to each other using the /docs/slug format:

See the [Architecture Overview](/docs/architecture) for more details.

The slug in the URL must match the slug field in the target page's frontmatter. Links work across locales -- the system resolves the correct localized version based on the reader's language setting.

Adding New Documentation

To add a new documentation page:

1. Create the English file in the appropriate category directory
2. Create the German file in the matching DE category directory
3. Set matching slugs -- Both files must have the same slug value
4. Choose a position -- Pick a number that places the page in the correct sort order within its category
5. Write the content -- Use standard Markdown with headings, tables, code blocks, and lists
6. Add a Related Docs section -- Link to other relevant pages at the bottom

File Naming Convention

Use the slug as the filename with a .md extension:

content/openclaw/docs/en/advanced/my-new-page.md
content/openclaw/docs/de/advanced/my-new-page.md

Both files would have slug: my-new-page in their frontmatter.

Content Guidelines

• Write in clear, direct language
• Use headings to organize content (start with ##, not #)
• Include code examples where helpful
• Add tables for comparing options or listing configurations
• End each page with a "Related Docs" section linking to related pages
• Do not include unverifiable claims or made-up statistics

German Translation Notes

The German version should be a natural German translation, not a word-for-word conversion:

• Use proper German umlauts (ä, ö, ü, ß), never ae, oe, ue, ss substitutions
• Localize the title and section fields
• Keep technical terms (Docker, API, SSH) unchanged
• Translate code comments if they contain user-facing text
• Use "du" (informal) for addressing the reader

Testing Documentation

Each documentation page has an associated RSpec test that verifies:

1. The Markdown file exists at the expected path
2. Frontmatter contains all required fields with correct values
3. The file syncs successfully through DocumentSyncService
4. The database record has the correct locale, slug, category, and content

Tests are located in spec/services/openclaw/docs_content/ and follow a consistent pattern for all documentation pages.

Related Docs

• Architecture Overview -- Technical architecture of the platform
• Best Practices -- Recommendations for using OpenClaw effectively