Overview

Documentation pages in Docs Kit are created using MDX (Markdown with JSX) files stored in the content/ directory. MDX allows you to write standard Markdown while incorporating React components for rich, interactive content.

Directory Structure

The content/ directory is organized by content type:

content/
├── docs/              # General documentation pages
│   ├── introduction.mdx
│   ├── installation.mdx
│   └── quick-start.mdx
│
├── api-reference/     # API documentation pages
│   ├── introduction.mdx
│   ├── authentication.mdx
│   └── otp/
│       ├── request.mdx
│       └── verify.mdx
│
└── changelog/         # Release notes and updates
    ├── mails.mdx
    └── texts.mdx

Creating Your First Page

touch content/docs/getting-started.mdx

---
title: "Getting Started Guide"
description: "Quick guide to get you up and running"
published: true
order: 5
---

## Welcome

This guide will help you get started with our platform.

<Callout status="info" title="Prerequisites">
  Make sure you have Node.js 18+ installed before continuing.
</Callout>

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting Started",
            "pages": [
              "/docs/getting-started"
            ]
          }
        ]
      }
    ]
  }
}

File Naming Conventions

Follow these conventions for consistent URLs:

• Use lowercase for filenames: getting-started.mdx not Getting-Started.mdx
• Use hyphens for spaces: api-reference.mdx not api_reference.mdx
• Be descriptive: configuring-webhooks.mdx not config.mdx
• Keep it concise: setup.mdx not how-to-setup-your-application.mdx

URL Mapping

The file path maps directly to the URL:

Organizing Content

By Feature

Group related content by feature or functionality:

content/docs/
├── authentication/
│   ├── overview.mdx
│   ├── api-keys.mdx
│   └── oauth.mdx
└── webhooks/
    ├── setup.mdx
    └── events.mdx

By User Journey

Organize content by the user's learning path:

content/docs/
├── getting-started/
│   ├── installation.mdx
│   └── first-project.mdx
├── guides/
│   ├── sending-emails.mdx
│   └── handling-webhooks.mdx
└── advanced/
    ├── rate-limiting.mdx
    └── custom-domains.mdx

By Content Type

Separate different types of documentation:

content/
├── docs/           # Conceptual documentation
├── api-reference/  # API endpoint documentation
├── guides/         # Step-by-step tutorials
└── changelog/      # Release notes

Nested Pages

Create nested page structures using subdirectories:

content/docs/api/
├── overview.mdx          → /docs/api/overview
├── authentication/
│   ├── oauth.mdx         → /docs/api/authentication/oauth
│   └── api-keys.mdx      → /docs/api/authentication/api-keys
└── endpoints/
    ├── users.mdx         → /docs/api/endpoints/users
    └── webhooks.mdx      → /docs/api/endpoints/webhooks

Internal Linking

Link to other documentation pages using relative or absolute paths:

<!-- Absolute path (recommended) -->

Check out the [Installation Guide](/docs/installation) for setup instructions.

<!-- Relative path -->

See the [Authentication section](./authentication) for more details.

<!-- Link to specific heading -->

Read about [Configuration Options](/docs/setup#configuration-options).

Adding Images

Store images in the public/ directory and reference them in your content:

![Dashboard Screenshot](/images/dashboard.png)

Organize images by section:

public/
└── images/
    ├── getting-started/
    │   └── setup.png
    └── api/
        └── response-example.png

Then reference them:

![Setup Steps](/images/getting-started/setup.png)

Draft Pages

Create draft pages that aren't visible on the site:

---
title: "Work in Progress"
description: "This page is not ready yet"
published: false
---

Draft pages:

• Won't appear in navigation
• Won't be included in search
• Won't be indexed by search engines
• Can still be accessed directly via URL (for review)

Best Practices

Keep Pages Focused

Each page should cover one topic thoroughly:

✅ Good: /docs/authentication/api-keys.mdx ❌ Too broad: /docs/authentication-and-security-and-permissions.mdx

Use Descriptive Titles

Make titles clear and searchable:

✅ Good: "Configuring Webhook Endpoints" ❌ Vague: "Configuration"

Structure Content Logically

Use headings to create a clear hierarchy:

## Main Topic

### Subtopic 1

Content about subtopic 1...

### Subtopic 2

Content about subtopic 2...

## Another Main Topic

Add Context with Callouts

Use callouts to highlight important information:

<Callout status="warning" title="Breaking Change">
  This feature requires API version 2.0 or higher.
</Callout>

Common Patterns

Tutorial Page

---
title: "Building Your First Integration"
description: "Step-by-step guide to creating your first API integration"
published: true
---

## Overview

Brief introduction to what you'll build...

## Prerequisites

<ParamField path="API Key" type="string" required>
  Get your API key from the dashboard
</ParamField>

## Steps

<Steps>
  <Step title="Setup">Instructions...</Step>
  ...
</Steps>

Reference Page

---
title: "Configuration Reference"
description: "Complete configuration options reference"
published: true
---

## Options

<ParamField path="apiKey" type="string" required>
  Your API authentication key
</ParamField>

<ParamField path="timeout" type="number">
  Request timeout in milliseconds. Default: 5000
</ParamField>

Troubleshooting

Page Not Showing

If your page doesn't appear:

1. Check published: true in frontmatter
2. Verify the page is added to docs.config.ts
3. Ensure the file path in config matches the actual file location
4. Restart the development server

Broken Links

If internal links are broken:

1. Use absolute paths starting with /
2. Don't include the .mdx extension
3. Check for typos in the path
4. Verify the target page exists and is published

Now that you understand how to create pages, learn about Frontmatter options to configure page metadata.