Documentation Integration

The documentation system (help center) provides a structured knowledge base for your product. Documentation pages are organized hierarchically with automatic sidebar navigation, search integration, and breadcrumbs. Users access docs at /docs or /help, and content is managed through the same Keystatic CMS as blog posts. This documentation you're reading is built with the same system.

The documentation system is a hierarchical content structure that renders Markdoc pages with automatic navigation, designed for product guides, API references, and user onboarding.

• Use documentation when: explaining how to use features, providing API references, creating step-by-step tutorials, or building a knowledge base that users reference repeatedly.
• Use the blog when: publishing announcements, thought leadership, or content with a publication date that becomes "old" over time.
• Use the FAQ when: answering common questions with short, direct answers that reduce support tickets.

Documentation Structure

Documentation is organized in apps/web/content/documentation/:

apps/web/content/documentation/
├── getting-started/
│   ├── getting-started.mdoc    # Section overview (metadata file)
│   ├── installation.mdoc
│   └── quickstart.mdoc
├── guides/
│   ├── guides.mdoc             # Section overview
│   ├── authentication.mdoc
│   └── organizations.mdoc
└── api/
    ├── api.mdoc                # Section overview
    └── reference.mdoc

Creating Sections

Sections are created automatically based on folder structure. Each section needs a metadata file that matches the folder name:

Option 1: File at same level as folder

content/documentation/
├── getting-started.mdoc        # Metadata for getting-started/
└── getting-started/
    ├── installation.mdoc
    └── quickstart.mdoc

Option 2: File inside folder with same name

content/documentation/
└── getting-started/
    ├── getting-started.mdoc    # Metadata for this section
    ├── installation.mdoc
    └── quickstart.mdoc

Section Metadata

The metadata file defines section properties:

---
title: "Getting Started"
description: "Learn how to get started with our product."
order: 1
status: "published"
collapsible: true
collapsed: false
---
This section covers installation and initial setup.

Page Frontmatter

Individual documentation pages use this frontmatter:

---
title: "Installation"
label: "Installation"
description: "Step-by-step installation guide."
order: 1
status: "published"
---

Navigation

The documentation system automatically generates:

• Sidebar navigation based on folder structure and order values
• Breadcrumbs showing the current location hierarchy
• Previous/Next links at the bottom of each page
• Table of contents from page headings (H2, H3)

Customizing Order

Control page order with the order field. Lower numbers appear first:

# installation.mdoc - appears first
order: 1
# quickstart.mdoc - appears second
order: 2
# advanced-setup.mdoc - appears last
order: 3

Pages without an order field default to 0 and are sorted alphabetically.

Custom Markdoc Components

Documentation supports these built-in Markdoc components:

Alert

{% alert type="default" title="Note" %}
This is an informational callout.
{% /alert %}
{% alert type="warning" title="Warning" %}
Be careful with this operation.
{% /alert %}
{% alert type="error" title="Error" %}
This action cannot be undone.
{% /alert %}

Code Blocks with Titles

```typescript

### Tabs
```markdown

Linking Between Pages

Use relative links to connect documentation pages:

See the [installation guide](./installation) for setup steps.
For advanced configuration, check [environment variables](../configuration/environment-variables).
Related: [Authentication overview](../../authentication/overview)

Search Integration

Documentation pages are automatically indexed for the built-in search. Ensure pages have:

• Descriptive title and description in frontmatter
• Clear heading hierarchy (H2, H3)
• Keywords in the first paragraph

Common Pitfalls

• Missing section metadata: Folders without a matching metadata file won't appear in navigation. Create a file named after the folder.
• Orphan pages: Pages not in a section folder may not appear in the sidebar. Organize all pages within sections.
• Broken relative links: Test links after restructuring. Moving a file breaks incoming relative links.
• Inconsistent order values: Gaps in order numbers are fine, but missing order values cause alphabetical sorting within that group.
• Draft pages in navigation: Draft pages (status: "draft") still appear in the admin UI but not on the public site. Don't forget to publish.
• Deeply nested sections: More than 3 levels of nesting becomes hard to navigate. Restructure if sections go deeper.
• Large pages: Break pages over 2000 words into multiple pages. Users scan documentation; they don't read it linearly.

Related Documentation

• CMS Integration - Keystatic configuration
• Blog System - Blog post management
• Internationalization - Multi-language documentation

Next: Changelog →