Quick Start

Getting Started

Create your first documentation page and configure navigation in minutes

Create Your First Page

Documentation pages are stored as MDX files in the content/ directory.

Create a new MDX file

Create a file at content/docs/my-first-page.mdx:

---
title: "My First Page"
description: "This is my first documentation page"
published: true
order: 10
---

# My First Page

Welcome to my documentation! This page is written in **MDX**, which combines Markdown with React components.

## Features

- Easy to write
- Supports React components
- Syntax highlighting
- And much more!

Add to navigation

Open config/docs.config.ts and add your page to the navigation:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting Started",
            "pages": [
              "/docs/introduction",
              "/docs/installation",
              "/docs/quick-start",
              "/docs/my-first-page"  // Add your page here
            ]
          }
        ]
      }
    ]
  }
}

View your page

Navigate to http://localhost:3000/docs/my-first-page to see your new page!

Understanding Frontmatter

Every MDX file must start with frontmatter - metadata about your page:

title

stringrequired

The page title displayed in navigation and browser tab

description

stringrequired

Short description used for SEO and page previews

published

boolean

Controls whether the page is visible. Set to false to hide drafts

Default:

order

number

Custom sort order for pages. Lower numbers appear first

openapi

string

OpenAPI endpoint reference like "GET /api/users" for API documentation pages

Writing Content

Markdown Basics

Docs Kit supports all standard Markdown syntax:

# Heading 1

## Heading 2

### Heading 3

**Bold text** and _italic text_

- Bullet point 1
- Bullet point 2

1. Numbered item
2. Another item

[Link text](https://example.com)

![Image alt text](/path/to/image.png)

Code Blocks

Add syntax-highlighted code blocks:

Using Callouts

Highlight important information with callouts:

This is an informational callout for general notices.

This is a warning callout for important cautions.

This is an error callout for critical information.

<Callout status="info" title="Title">
  Your message here
</Callout>

Adding Steps

Create step-by-step guides:

First step

Do this first thing

Second step

Then do this

Final step

Complete with this

<Steps>
  <Step title="Step title">Step content</Step>
</Steps>

Tabbed Content

Organize content with tabs:

npm install package-name

bash pnpm add package-name

bash yarn add package-name

bun add package-name

Navigation is defined in config/docs.config.ts:

Basic Structure

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["/docs/introduction", "/docs/installation"]
          },
          {
            "group": "Guides",
            "pages": ["/docs/writing-content", "/docs/components"]
          }
        ]
      }
    ]
  }
}

Multiple Tabs

Create separate sections for different content types:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [...]
      },
      {
        "tab": "API Reference",
        "groups": [...]
      },
      {
        "tab": "Changelog",
        "hideToc": true,  // Hide table of contents
        "groups": [...]
      }
    ]
  }
}

Pages appear in the order listed in the config, not alphabetically:

{
  "pages": [
    "/docs/introduction", // Shows first
    "/docs/installation", // Shows second
    "/docs/quick-start" // Shows third
  ]
}

Customize Your Site

Change Colors

Choose from 10 color palettes in docs.config.ts:

{
  "colorPalette": "teal" // teal, blue, purple, green, etc.
}

Update Logo

Replace logo files in public/logo/:

light.svg - Logo for light mode
dark.svg - Logo for dark mode

Then update config:

{
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg"
  }
}

Add external links to navbar:

{
  "navbar": {
    "links": [
      { "label": "GitHub", "href": "https://github.com/..." },
      { "label": "Discord", "href": "https://discord.gg/..." },
      { "label": "Sign Up", "href": "/signup", "primary": true }
    ]
  }
}

Create API Documentation

Document REST APIs using OpenAPI integration:

Add OpenAPI spec

Place your OpenAPI specification at public/openapi.json

Create API page

Create an MDX file with openapi frontmatter:

---
title: "Create User"
description: "Create a new user account"
openapi: "POST /api/users"
published: true
---

Additional documentation about this endpoint...

Configure spec path

Update docs.config.ts:

{
  "openapi": {
    "specPath": "public/openapi.json"
  }
}

The page will automatically display:

Interactive "Try It" button
Request parameters and body schema
Response schemas for all status codes
Code examples in multiple languages
Authentication requirements

Next Steps

Explore Components

Learn about all available MDX components

Configure Theme

Customize colors, fonts, and styling

Add Content

Create more documentation pages

Deploy

Deploy your site to Vercel, Netlify, or another platform

Common Tasks

Adding Images

Place images in public/ and reference them:

![Alt text](/images/screenshot.png)

Internal Links

Link to other documentation pages:

[Installation Guide](/docs/installation)
[API Reference](/api-reference/endpoint)

Code Highlighting

Specify language for syntax highlighting:

```typescript
const greeting: string = "Hello, world!";
```

Create a page without adding to sidebar:

---
title: "Hidden Page"
description: "This page is not in the sidebar"
published: true
---

Don't add the page path to docs.config.ts - it's accessible by URL but won't appear in navigation.

Troubleshooting

Make sure the page path in docs.config.ts matches the file path exactly, and that published: true in frontmatter.

Check that all frontmatter is valid YAML and all MDX components are properly closed.

You're now ready to build your documentation site! Explore the Components documentation to see all available MDX components.