Site Configuration
Site configuration: documentation.json options and examples.
Overview
Configure your documentation site using the documentation.json file. This file controls your site's branding, navigation structure, SEO settings, and API documentation generation.
Site Configuration
Basic site settings that control your documentation's identity and behavior.
{
"name": "Documentation.AI",
"initialRoute": "getting-started/introduction"
}
Site name displayed in the browser title, navigation header, and social media previews.
Default page path when users visit the root URL. Points to an MDX file in your documentation project (all pages must be in MDX format). Specify the path without the .mdx extension.
Branding Configuration
Logo Configuration
Configure logo variants for different themes and sizes. All logo fields are optional and fallback to default assets.
{
"logo-dark": "https://example.com/logo-dark.svg",
"logo-light": "https://example.com/logo-light.svg",
"logo-small-dark": "https://example.com/favicon-dark.svg",
"logo-small-light": "https://example.com/favicon-light.svg"
}
Main logo displayed in dark theme. Supports PNG, SVG, WEBP formats.
Main logo displayed in light theme.
Small logo/favicon for dark theme. Used in browser tabs and mobile view.
Small logo/favicon for light theme.
Brand Colors
Customize your site's color scheme with automatic contrast optimization.
{
"colors": {
"light": {
"brand": "#3143e3",
"heading": "#1a1a1a",
"text": "#374151"
},
"dark": {
"brand": "#85a1ff",
"heading": "#f2f2f2",
"text": "#c1c1c1"
}
}
}
Light Theme Colors
Color scheme for light mode appearance.
Dark Theme Colors
Color scheme for dark mode appearance.
Navbar Configuration
Configure the top navigation bar with action buttons and links.
{
"navbar": {
"actions": {
"primary": {
"title": "Get Started",
"link": "https://dashboard.example.com/signup"
},
"links": [
{
"title": "Login",
"link": "https://dashboard.example.com/login"
},
{
"title": "Support",
"link": "mailto:support@example.com"
}
]
}
}
}
Primary Action Button
Configure the main call-to-action button that appears prominently in your navbar.
Main action button for user engagement (e.g., "Get Started", "Sign Up", "Try Now").
Secondary Navigation Links
Add supplementary text links for additional navigation options.
Array of secondary navigation links displayed as text in the navbar.
Navigation Structure
Configure your documentation site's navigation hierarchy using different container types. Each container must choose exactly ONE child container type.
Pages Navigation
Flat page list for simple sites with minimal hierarchy.
{
"navigation": {
"pages": [
{
"title": "Introduction",
"path": "getting-started/introduction",
"icon": "star"
},
{
"title": "API Reference",
"path": "api/overview",
"icon": "code"
},
{
"title": "External Resource",
"href": "https://github.com/company/repo",
"icon": "github"
}
]
}
}
Supported Children: Individual page items only (see Page Properties)
Groups Navigation
Section-based organization with collapsible groups. Groups can contain nested groups for deeper hierarchical organization.
{
"navigation": {
"groups": [
{
"group": "Getting Started",
"icon": "rocket",
"expandable": false,
"pages": [
{
"title": "Introduction",
"path": "getting-started/introduction",
"icon": "star"
},
{
"group": "Advanced Setup",
"expandable": true,
"pages": [
{
"title": "Configuration",
"path": "getting-started/configuration"
}
]
}
]
},
{
"group": "API Reference",
"icon": "code",
"openapi": "api/openapi.json",
"pages": [
{
"title": "Authentication",
"path": "api/authentication"
}
]
}
]
}
}
Supported Children: Pages Arrays (containing individual page items and nested group items)
Tabs Navigation
Tabbed navigation interface with horizontal navigation bar. Creates distinct sections with separate URL paths.
{
"navigation": {
"tabs": [
{
"tab": "Documentation",
"icon": "book",
"groups": [
{
"group": "Getting Started",
"pages": [
{
"title": "Introduction",
"path": "docs/introduction"
}
]
}
]
},
{
"tab": "API Reference",
"icon": "code",
"pages": [
{
"title": "Authentication",
"path": "api/authentication"
}
]
},
{
"tab": "Blog",
"icon": "newspaper",
"href": "https://blog.example.com"
}
]
}
}
Supported Children: Menus, Groups, or Pages
Menus Navigation
Menu-based navigation for sub-sections within other containers.
{
"navigation": {
"tabs": [
{
"tab": "Developer Tools",
"icon": "terminal",
"menus": [
{
"menu": "API Reference",
"icon": "api",
"description": "Complete API documentation",
"groups": [
{
"group": "Core Endpoints",
"pages": [
{
"title": "Users API",
"path": "api/users"
}
]
}
]
},
{
"menu": "SDKs",
"icon": "package",
"pages": [
{
"title": "JavaScript SDK",
"path": "sdk/javascript"
}
]
}
]
}
]
}
}
Supported Children: Groups or Pages
Versions Navigation
Version-based organization with dropdown selector for different product versions or API versions.
{
"navigation": {
"versions": [
{
"version": "v2.0",
"icon": "version",
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Endpoints",
"pages": [
{
"title": "Users API",
"path": "v2/api/users"
}
]
}
]
}
]
},
{
"version": "v1.0",
"groups": [
{
"group": "Legacy API",
"pages": [
{
"title": "Migration Guide",
"path": "v1/migration-guide"
}
]
}
]
}
]
}
}
Supported Children: Dropdowns, Tabs, Menus, Groups, or Pages
Dropdowns Navigation
Dropdown menu navigation for complex sites with expandable sections in the sidebar.
{
"navigation": {
"dropdowns": [
{
"dropdown": "Documentation",
"icon": "book",
"description": "Complete documentation",
"tabs": [
{
"tab": "Getting Started",
"pages": [
{
"title": "Introduction",
"path": "introduction"
}
]
}
]
},
{
"dropdown": "API Reference",
"icon": "code",
"groups": [
{
"group": "Core API",
"pages": [
{
"title": "Authentication",
"path": "api/authentication"
}
]
}
]
},
{
"dropdown": "External Resources",
"href": "https://resources.example.com"
}
]
}
}
Supported Children: Tabs, Menus, Groups, or Pages
Page Properties
Individual page configuration within any navigation structure.
{
"title": "OpenAPI Schema Import",
"path": "api-documentation/openapi-schema-import",
"icon": "key",
"href": "https://external-link.com",
"method": "GET",
"tags": "API"
}
Individual Page Configuration
Configure properties for individual pages within your navigation structure.
MDX File Format Required: All documentation pages must be in MDX format. When referencing files in your configuration, always omit the .mdx extension from the path (e.g., use "getting-started/introduction" instead of "getting-started/introduction.mdx").
Basic Page Settings
Display name shown in navigation and browser title.
Relative path to your MDX file in your documentation project. All pages must be in MDX format - specify the path without the .mdx extension (e.g., "getting-started/introduction" for the file getting-started/introduction.mdx).
External URL for links that open in new tabs. Use instead of path for external links.
Visual Customization
Page icon from the Lucide React icon library.
API Documentation Pages
HTTP method for API endpoint pages (e.g., "GET", "POST", "DELETE").
Navigation Group Configuration
Configure collapsible sections that organize related pages together.
Group Identity
Display name shown in the sidebar navigation.
Visual icon from the Lucide React icon library.
Group Behavior
Whether users can collapse/expand this group. Default: true.
API Documentation Integration
Path to OpenAPI specification file for automatic API documentation generation within this group. Supports both JSON (.json) and YAML (.yaml, .yml) formats.
Group Contents
Array of pages and nested groups contained within this group. See Mixed Content in Pages Arrays for details.
Mixed Content in Pages Arrays
Pages arrays can contain both individual page items AND group items mixed together:
{
"pages": [
{
"group": "Components",
"icon": "box",
"expandable": true,
"pages": [
{
"title": "Headings and Text",
"path": "components/heading-and-text",
"icon": "type"
},
{
"title": "Code and Groups",
"path": "components/code-blocks-and-groups",
"icon": "code"
}
]
},
{
"title": "External Resource",
"href": "https://external.com",
"icon": "link"
}
]
}
This demonstrates how:
- Individual pages (
Components Overview,External Resource) exist alongside - Group items (
Componentsgroup) with their own nested pages - All within the same
pagesarray
OpenAPI Integration
Generate comprehensive API documentation automatically from OpenAPI specifications.
{
"navigation": {
"groups": [
{
"group": "API Reference",
"openapi": "api/openapi.yaml",
"pages": [
{
"title": "Authentication",
"path": "api/authentication"
},
{
"title": "Users API",
"path": "api/users"
}
]
}
]
}
}
{
"navigation": {
"groups": [
{
"group": "API Documentation",
"openapi": "api/v1/openapi.json",
"pages": [
{
"title": "Overview",
"path": "api/overview"
},
{
"group": "Products API",
"openapi": "api/v2/products.yml",
"pages": [
{
"title": "Get Products",
"path": "api/products/list"
}
]
}
]
}
]
}
}
Path to OpenAPI 3.0+ specification file within your documentation project. Supports both JSON (.json) and YAML (.yaml, .yml) formats.
OpenAPI Features
- Automatic endpoint generation - Creates individual
.mdxfiles for each API endpoint - Interactive examples - Request/response components with syntax highlighting
- Parameter documentation - Automatic ParamField generation from schema
- Authentication docs - Security scheme documentation
- Status code handling - Multiple response examples per endpoint
- Inheritance - Child elements inherit parent OpenAPI specs unless overridden
SEO Configuration
Configure search engine optimization and meta tag behavior.
{
"seo": {
"robots:index": true,
"robots:follow": true
}
}
Search Engine Indexing
Allow search engines to index your documentation pages. Default: true.
Search Engine Link Following
Allow search engines to follow links within your documentation. Default: true.
Complete Example
{
"name": "Documentation.AI",
"initialRoute": "getting-started/introduction",
"logo-dark": "https://example.com/logo-dark.svg",
"logo-light": "https://example.com/logo-light.svg",
"logo-small-dark": "https://example.com/favicon-dark.svg",
"logo-small-light": "https://example.com/favicon-light.svg",
"colors": {
"light": {
"brand": "#3143e3",
"heading": "#1a1a1a",
"text": "#374151"
},
"dark": {
"brand": "#85a1ff",
"heading": "#f2f2f2",
"text": "#c1c1c1"
}
},
"navbar": {
"actions": {
"primary": {
"title": "Get Started",
"link": "https://dashboard.example.com/signup"
},
"links": [
{
"title": "Login",
"link": "https://dashboard.example.com/login"
}
]
}
},
"navigation": {
"tabs": [
{
"tab": "Documentation",
"icon": "book",
"groups": [
{
"group": "Getting Started",
"icon": "rocket",
"expandable": false,
"pages": [
{
"title": "Introduction",
"path": "getting-started/introduction",
"icon": "star"
},
{
"title": "Quickstart",
"path": "getting-started/quickstart",
"icon": "zap"
}
]
},
{
"group": "API Reference",
"icon": "code",
"openapi": "api/openapi.json",
"expandable": true,
"pages": [
{
"title": "Authentication",
"path": "api/authentication",
"icon": "key"
},
{
"title": "Users API",
"path": "api/users",
"icon": "users"
}
]
}
]
}
]
},
"seo": {
"robots:index": true,
"robots:follow": true
}
}