Configuration Reference

Content

Complete reference for all configuration options in docs.config.ts

Overview

The config/docs.config.ts file is the central configuration for your documentation site. It controls navigation, styling, metadata, and features.

File Location

config/
└── docs.config.ts

After modifying docs.config.ts, restart your development server to see changes.

Complete Example

{
  "name": "Documentation",
  "description": "Comprehensive guides and documentation",
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg"
  },
  "appearance": {
    "default": "light"
  },
  "favicon": "/favicon.svg",
  "colorPalette": "teal",
  "navbar": {
    "links": [
      { "label": "GitHub", "href": "https://github.com" },
      { "label": "Sign Up", "href": "/signup", "primary": true }
    ]
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["/docs/introduction", "/docs/installation"]
          }
        ]
      }
    ]
  },
  "footer": {
    "socials": {
      "github": "https://github.com",
      "twitter": "https://twitter.com"
    }
  },
  "search": {
    "prompt": "Search documentation..."
  },
  "primaryTab": {
    "name": "Documentation"
  },
  "openapi": {
    "specPath": "public/openapi.json"
  }
}

Site Metadata

name

stringrequired

The name of your documentation site.

"name": "Acme API Documentation"

Used in:

Browser title (combined with page title)
SEO meta tags
Social media cards

description

stringrequired

Brief description of your documentation site.

"description": "Complete guides and API reference for Acme platform"

Used in:

Homepage meta description
Open Graph tags
Search engine results

Branding

logo.light

stringrequired

Path to logo for light mode (dark-colored logo on light background).

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

logo.dark

stringrequired

Path to logo for dark mode (light-colored logo on dark background).

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

favicon

string

Path to favicon file in public/ directory.

"favicon": "/favicon.svg"

Supported formats: .svg, .ico, .png

colorPalette

string

Color palette for the site theme.

Options: teal (default), blue, purple, pink, green, orange, red, cyan, gray, yellow

"colorPalette": "purple"

Appearance

appearance.default

string

Default color mode when users first visit.

Options: light (default), dark, system

"appearance": {
  "default": "system"
}

light - Always start in light mode
dark - Always start in dark mode
system - Follow user's system preference

The navigation structure defines your sidebar organization.

"navigation": {
  "tabs": [...]
}

Array of navigation tabs. Each tab contains groups of pages.

"tabs": [
  {
    "tab": "Documentation",
    "groups": [...]
  },
  {
    "tab": "API Reference",
    "groups": [...]
  }
]

Tab Object

tab

stringrequired

Display name of the tab in navigation.

"tab": "Documentation"

hideToc

boolean

Hide table of contents for all pages in this tab.

{
  "tab": "Changelog",
  "hideToc": true,
  "groups": [...]
}

Useful for changelog, landing pages, or pages without headings.

groups

arrayrequired

Array of page groups within the tab.

"groups": [
  {
    "group": "Getting Started",
    "pages": [...]
  }
]

Group Object

group

stringrequired

Display name of the group in sidebar.

"group": "Getting Started"

pages

arrayrequired

Array of page paths within the group.

"pages": [
  "/docs/introduction",
  "/docs/installation",
  "/docs/quick-start"
]

Important:

Use URL paths, not file paths
Omit .mdx extension
Must match content file location
Order in array determines display order

"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "pages": [
            "/docs/introduction",
            "/docs/installation",
            "/docs/quick-start"
          ]
        },
        {
          "group": "Guides",
          "pages": [
            "/docs/authentication",
            "/docs/webhooks",
            "/docs/error-handling"
          ]
        }
      ]
    },
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users",
          "pages": [
            "/api-reference/users/create",
            "/api-reference/users/get",
            "/api-reference/users/update",
            "/api-reference/users/delete"
          ]
        }
      ]
    },
    {
      "tab": "Changelog",
      "hideToc": true,
      "groups": [
        {
          "group": "Updates",
          "pages": [
            "/changelog/2024",
            "/changelog/2023"
          ]
        }
      ]
    }
  ]
}

Array of links to display in the navbar.

"navbar": {
  "links": [
    { "label": "GitHub", "href": "https://github.com/..." },
    { "label": "Blog", "href": "https://blog.example.com" },
    { "label": "Sign Up", "href": "/signup", "primary": true }
  ]
}

Link Object

label

stringrequired

Display text for the link.

"label": "GitHub"

href

stringrequired

URL or path for the link. Can be external or internal.

"href": "https://github.com/username/repo"

primary

boolean

Style link as primary button (filled, emphasized).

{ "label": "Sign Up", "href": "/signup", "primary": true }

Visual difference:

primary: false (default) - Ghost button style
primary: true - Filled button with brand color

"navbar": {
  "links": [
    { "label": "GitHub", "href": "https://github.com/user/repo" },
    { "label": "Discord", "href": "https://discord.gg/..." }
  ]
}

"navbar": {
  "links": [
    { "label": "Pricing", "href": "https://example.com/pricing" },
    { "label": "Blog", "href": "https://blog.example.com" },
    { "label": "Login", "href": "/login" },
    { "label": "Sign Up", "href": "/signup", "primary": true }
  ]
}

"navbar": {
  "links": [
    { "label": "API Status", "href": "https://status.example.com" },
    { "label": "Get API Key", "href": "/dashboard", "primary": true }
  ]
}

footer.socials

object

Social media links displayed in the footer.

"footer": {
  "socials": {
    "github": "https://github.com/username",
    "twitter": "https://twitter.com/username",
    "discord": "https://discord.gg/invite",
    "linkedin": "https://linkedin.com/company/name"
  }
}

Supported platforms:

github - GitHub profile or organization
twitter - Twitter/X profile
discord - Discord invite link
linkedin - LinkedIn profile or company

"footer": {
  "socials": {
    "github": "https://github.com/acme",
    "twitter": "https://twitter.com/acme",
    "discord": "https://discord.gg/acme"
  }
}

Icons are automatically displayed for each platform with proper branding colors.

Search

search.prompt

string

Placeholder text in the search input.

"search": {
  "prompt": "Search documentation..."
}

Default: "Search..."

The search feature automatically indexes:

Page titles
Page descriptions
Heading text
Body content

Users can open search with Cmd/Ctrl + K from anywhere on the site.

Primary Tab

primaryTab.name

string

The default tab to show when users first visit the site.

"primaryTab": {
  "name": "Documentation"
}

Must match the tab name from navigation.tabs.

Primary Tab Behavior

Users land on the first page of the primary tab
The primary tab is highlighted in navigation
Breadcrumbs start from the primary tab
Homepage redirects to primary tab's first page

Example:

"navigation": {
  "tabs": [
    {
      "tab": "Documentation",  // Primary tab
      "groups": [...]
    },
    {
      "tab": "API Reference",
      "groups": [...]
    }
  ]
},
"primaryTab": {
  "name": "Documentation"  // Matches tab name above
}

OpenAPI

openapi.specPath

string

Path to OpenAPI specification file.

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

Can be:

Local file: public/openapi.json
Remote URL: https://api.example.com/openapi.json

Learn more in the OpenAPI Setup guide.

Environment Variables

Some settings can be overridden with environment variables:

NEXT_PUBLIC_SITE_URL

string

The public URL of your documentation site.

NEXT_PUBLIC_SITE_URL=https://docs.example.com

Used for:

Canonical URLs
Social media cards
Sitemap generation

NEXT_PUBLIC_GA_ID

string

Google Analytics measurement ID for tracking.

NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

Add analytics without modifying code.

Configuration Tips

For sites with many pages, organize navigation into logical groups:

"groups": [
  {
    "group": "Getting Started",
    "pages": ["/docs/intro", "/docs/install"]
  },
  {
    "group": "Core Concepts",
    "pages": ["/docs/auth", "/docs/errors", "/docs/webhooks"]
  },
  {
    "group": "Advanced",
    "pages": ["/docs/rate-limits", "/docs/custom-domains"]
  }
]

Multiple Documentation Sections

Use tabs to separate different types of content:

"tabs": [
  {
    "tab": "Guides",           // Tutorials and how-tos
    "groups": [...]
  },
  {
    "tab": "API Reference",    // Endpoint documentation
    "groups": [...]
  },
  {
    "tab": "SDKs",             // Language-specific guides
    "groups": [...]
  },
  {
    "tab": "Changelog",        // Release notes
    "hideToc": true,
    "groups": [...]
  }
]

Link Ordering

Control display order explicitly in the pages array:

"pages": [
  "/docs/introduction",    // Shown first
  "/docs/installation",    // Shown second
  "/docs/quick-start",     // Shown third
  "/docs/advanced"         // Shown fourth
]

Alphabetical order is not used - only array order matters.

Validation

Docs Kit validates your configuration at build time:

Common Errors

Missing required field:

{
  "name": "My Docs"
  // ❌ Error: Missing required field 'description'
}

Invalid navigation structure:

"pages": [
  "/docs/nonexistent-page"  // ❌ Error: File doesn't exist
]

Invalid color palette:

"colorPalette": "rainbow"  // ❌ Error: Invalid palette name

Mismatched primary tab:

"primaryTab": {
  "name": "Guides"  // ❌ Error: No tab named "Guides" in navigation
}

Complete Configuration Template

{
  "name": "Your Documentation",
  "description": "Comprehensive guides and documentation for your platform",
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg"
  },
  "appearance": {
    "default": "system"
  },
  "favicon": "/favicon.svg",
  "colorPalette": "teal",
  "navbar": {
    "links": [
      { "label": "Website", "href": "https://example.com" },
      { "label": "GitHub", "href": "https://github.com/..." },
      { "label": "Get Started", "href": "/signup", "primary": true }
    ]
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting Started",
            "pages": [
              "/docs/introduction",
              "/docs/installation",
              "/docs/quick-start"
            ]
          },
          {
            "group": "Guides",
            "pages": ["/docs/authentication", "/docs/webhooks"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "groups": [
          {
            "group": "Endpoints",
            "pages": ["/api-reference/users", "/api-reference/webhooks"]
          }
        ]
      }
    ]
  },
  "footer": {
    "socials": {
      "github": "https://github.com/...",
      "twitter": "https://twitter.com/...",
      "discord": "https://discord.gg/..."
    }
  },
  "search": {
    "prompt": "Search documentation..."
  },
  "primaryTab": {
    "name": "Documentation"
  },
  "openapi": {
    "specPath": "public/openapi.json"
  }
}

Next, learn about the MDX Components available for rich content.

Getting Started

Content

Components

OpenAPI