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:[email protected]"
}
]
}
}
}
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 Architecture
Our documentation system organizes information in three conceptual layers to help developers, writers, and AI agents reason about structure, rendering, and content discovery.
Understanding the Three Layers
Dimensions → Views → Content
- Dimensions define where in your documentation the reader currently is (e.g., which product, version, or language)
- Views define how content is organized and navigated within that context (e.g., tabs or dropdowns)
- Content defines what the reader sees (e.g., groups and pages of documentation)
Navigation Rule: Each container must choose exactly ONE child type. For
example, a tab can contain groups OR pages OR dropdowns, but not
multiple types simultaneously.
Dimensions Layer
Dimensions describe the organizational axes of your documentation. They define contextual boundaries that filter what content appears to readers.
Supported Dimension Types
Organize documentation by different products or services your company offers.
Organize documentation by product versions or API versions.
Organize documentation by language for internationalization.
Dimension Behavior
- Optional: Use dimensions only when needed for your documentation structure
- Flexible Order: Dimensions can be nested in any order (e.g.,
products → versions → languagesorversions → languages) - Single Root: Navigation must start with one dimension type at the root level
- User Selection: When users select a dimension value, the system filters content to show only what belongs to that context
- UI Display: Currently rendered as dropdown selectors at the top of your documentation
Dimension Configuration
Each dimension item must have a unique identifier and can contain nested dimensions or views.
{
"navigation": {
"products": [
{
"product": "API Platform",
"icon": "code",
"tabs": [
{
"tab": "Documentation",
"groups": [...]
}
]
},
{
"product": "Dashboard",
"icon": "layout-dashboard",
"pages": [...]
}
]
}
}
{
"navigation": {
"versions": [
{
"version": "v2.0",
"icon": "badge",
"tabs": [
{
"tab": "API Reference",
"groups": [...]
}
]
},
{
"version": "v1.0",
"icon": "badge",
"groups": [...]
}
]
}
}
{
"navigation": {
"languages": [
{
"language": "English",
"icon": "languages",
"tabs": [
{
"tab": "Documentation",
"groups": [...]
}
]
},
{
"language": "Español",
"icon": "languages",
"tabs": [...]
}
]
}
}
Multi-Dimension Configuration
You can nest multiple dimensions to create sophisticated organizational structures. Dimensions can be combined in any order based on your documentation needs.
{
"navigation": {
"products": [
{
"product": "API Platform",
"icon": "code",
"versions": [
{
"version": "v2.0",
"icon": "badge",
"tabs": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": [
{
"title": "Introduction",
"path": "api-v2/introduction"
}
]
}
]
}
]
},
{
"version": "v1.0",
"icon": "badge",
"tabs": [...]
}
]
},
{
"product": "Dashboard",
"icon": "layout-dashboard",
"versions": [
{
"version": "v2.0",
"icon": "badge",
"tabs": [...]
}
]
}
]
}
}
{
"navigation": {
"versions": [
{
"version": "v2.0",
"icon": "badge",
"products": [
{
"product": "API Platform",
"icon": "code",
"tabs": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": [
{
"title": "Introduction",
"path": "v2/api/introduction"
}
]
}
]
}
]
},
{
"product": "Dashboard",
"icon": "layout-dashboard",
"tabs": [...]
}
]
},
{
"version": "v1.0",
"icon": "badge",
"products": [...]
}
]
}
}
{
"navigation": {
"products": [
{
"product": "API Platform",
"icon": "code",
"versions": [
{
"version": "v2.0",
"icon": "badge",
"languages": [
{
"language": "English",
"icon": "languages",
"tabs": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": [
{
"title": "Introduction",
"path": "api-v2/en/introduction"
}
]
}
]
}
]
},
{
"language": "Español",
"icon": "languages",
"tabs": [
{
"tab": "Documentación",
"groups": [...]
}
]
}
]
}
]
}
]
}
}
{
"navigation": {
"versions": [
{
"version": "v2.0",
"icon": "badge",
"languages": [
{
"language": "English",
"icon": "languages",
"tabs": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": [
{
"title": "Introduction",
"path": "v2/en/introduction"
}
]
}
]
}
]
},
{
"language": "Español",
"icon": "languages",
"tabs": [
{
"tab": "Documentación",
"groups": [...]
}
]
}
]
},
{
"version": "v1.0",
"icon": "badge",
"languages": [...]
}
]
}
}
Dimension Order Matters: The order of nested dimensions affects user
experience. Consider what users will select first. For example, products → versions works well when users first choose a product, then its version. Use
versions → products if version selection is more important for your use
case.
Views Layer
Views control how content is organized and navigated within a chosen dimension context. They determine the navigation layout and user interaction patterns.
Supported View Types
Horizontal navigation bar for switching between parallel sections like "Guides" and "API Reference".
Collapsible dropdown menus for selecting between sub-categories in the sidebar.
View Nesting Patterns
Our standard UI templates support these view combinations:
| Pattern | Structure | Use Case |
|---|---|---|
| Pattern 1 | Dropdown → Tabs → Dropdown | Complex navigation with categorized sections |
| Pattern 2 | Dropdown → Dropdown | Hierarchical categorization without tabs |
| Pattern 3 | Tabs → Dropdown → Dropdown | Tab-based sections with nested categories |
Enterprise Customization: Custom UI templates can support additional view combinations beyond these standard patterns. Contact support for enterprise options.
Tab Configuration
Tabs create horizontal navigation sections that are visible at the top of your documentation.
{
"tabs": [
{
"tab": "Documentation",
"icon": "book",
"groups": [
{
"group": "Getting Started",
"pages": [
{
"title": "Introduction",
"path": "introduction"
}
]
}
]
},
{
"tab": "API Reference",
"icon": "code",
"pages": [
{
"title": "Authentication",
"path": "api/auth"
}
]
},
{
"tab": "External Link",
"icon": "external-link",
"href": "https://blog.example.com"
}
]
}
Tab Properties:
Display name for the tab shown in the navigation bar.
Visual icon from the Lucide React icon library.
External URL for tabs that link outside your documentation. Use instead of nested content.
Tab Children (choose ONE):
dropdowns- Array of dropdown itemsgroups- Array of content groupspages- Array of individual pages
Dropdown Configuration
Dropdowns create collapsible sections in the sidebar for hierarchical navigation.
{
"dropdowns": [
{
"dropdown": "Core Features",
"icon": "lightbulb",
"description": "Essential platform capabilities",
"tabs": [
{
"tab": "User Guide",
"groups": [...]
}
]
},
{
"dropdown": "Advanced Topics",
"icon": "graduation-cap",
"dropdowns": [
{
"dropdown": "Integrations",
"pages": [...]
}
]
}
]
}
Dropdown Properties:
Display name for the dropdown shown in the sidebar.
Visual icon from the Lucide React icon library.
Optional descriptive text shown below the dropdown title.
External URL for dropdowns that link outside your documentation. Use instead of nested content.
Dropdown Children (choose ONE):
tabs- Array of tab itemsdropdowns- Array of nested dropdown itemsgroups- Array of content groupspages- Array of individual pages
Content Layer
The content layer contains your actual documentation files organized into groups and pages. This is what readers consume after selecting their context and navigation path.
Simple Navigation (No Dimensions)
For straightforward documentation without version or product variants, start directly with views or content.
{
"navigation": {
"tabs": [
{
"tab": "Documentation",
"icon": "book",
"groups": [
{
"group": "Getting Started",
"pages": [
{
"title": "Introduction",
"path": "introduction"
}
]
}
]
}
]
}
}
{
"navigation": {
"groups": [
{
"group": "Getting Started",
"icon": "rocket",
"expandable": false,
"pages": [
{
"title": "Introduction",
"path": "introduction"
}
]
}
]
}
}
{
"navigation": {
"pages": [
{
"title": "Introduction",
"path": "introduction",
"icon": "star"
},
{
"title": "API Reference",
"path": "api/overview",
"icon": "code"
}
]
}
}
Groups Configuration
Groups organize related pages into collapsible sections within your sidebar navigation.
{
"groups": [
{
"group": "Getting Started",
"icon": "rocket",
"expandable": false,
"pages": [
{
"title": "Introduction",
"path": "introduction"
},
{
"title": "Quickstart",
"path": "quickstart"
}
]
},
{
"group": "API Reference",
"icon": "code",
"openapi": "api/openapi.yaml",
"expandable": true,
"pages": [
{
"title": "Authentication",
"path": "api/authentication"
}
]
}
]
}
Group Properties:
Display name shown in the sidebar navigation.
Visual icon from the Lucide React icon library.
Whether users can collapse/expand this group. Default: true.
Path to OpenAPI specification file for automatic API documentation generation.
Supports both JSON (.json) and YAML (.yaml, .yml) formats.
Array of pages and nested groups. Pages arrays can contain both individual page items AND nested group items mixed together.
Group Children (choose ONE):
- Array of individual page items
- Array mixing page items with nested group items
Pages Configuration
Pages are the individual documentation files that contain your content.
{
"pages": [
{
"title": "Introduction",
"path": "getting-started/introduction",
"icon": "star"
},
{
"title": "API Endpoints",
"path": "api/endpoints",
"icon": "code",
"method": "GET",
"tags": "API"
},
{
"title": "External Resource",
"href": "https://github.com/company/repo",
"icon": "external-link"
}
]
}
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").
Page Properties:
Display name shown in navigation and browser title.
Relative path to your MDX file without the .mdx extension (e.g.,
"getting-started/introduction"). Required unless using href.
External URL for links that open in new tabs. Use instead of path for
external resources.
Page icon from the Lucide React icon library.
HTTP method for API endpoint pages (e.g., "GET", "POST", "DELETE"). Used
for visual indicators in API documentation.
Mixed Content in Pages Arrays
Pages arrays support flexible organization by mixing individual pages with nested groups:
{
"pages": [
{
"title": "Overview",
"path": "components/overview",
"icon": "eye"
},
{
"group": "Layout Components",
"icon": "layout",
"expandable": true,
"pages": [
{
"title": "Grid",
"path": "components/grid"
},
{
"title": "Container",
"path": "components/container"
}
]
},
{
"title": "External Design System",
"href": "https://design.example.com",
"icon": "palette"
}
]
}
This example demonstrates:
- Individual pages (
Overview,External Design System) appear alongside - Nested group items (
Layout Components) with their own page collections - All coexisting 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.
Navigation Examples
Comprehensive examples demonstrating different navigation architectures for various use cases.
Example 1: Simple Documentation (No Dimensions)
Basic documentation site with tabs and groups, no version or product variants.
{
"name": "Documentation.AI",
"initialRoute": "getting-started/introduction",
"colors": {
"light": { "brand": "#3143e3" },
"dark": { "brand": "#85a1ff" }
},
"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"
}
]
}
]
},
{
"tab": "API Reference",
"icon": "code",
"groups": [
{
"group": "Endpoints",
"openapi": "api/openapi.json",
"pages": [
{
"title": "Authentication",
"path": "api/auth"
}
]
}
]
}
]
}
}
Example 2: Version Dimension Only
Documentation with multiple versions but single product.
{
"name": "API Documentation",
"navigation": {
"versions": [
{
"version": "v2.0",
"icon": "badge",
"tabs": [
{
"tab": "Guides",
"icon": "book",
"groups": [
{
"group": "Getting Started",
"pages": [
{
"title": "Introduction",
"path": "v2/introduction"
}
]
}
]
},
{
"tab": "API Reference",
"icon": "code",
"groups": [
{
"group": "Core API",
"openapi": "api/v2/openapi.yaml",
"pages": []
}
]
}
]
},
{
"version": "v1.0",
"icon": "badge",
"groups": [
{
"group": "Legacy Documentation",
"pages": [
{
"title": "Migration Guide",
"path": "v1/migration"
}
]
}
]
}
]
}
}
Example 3: Multiple Dimensions (Products → Versions → Languages)
Complex documentation with products, versions, and language support.
{
"name": "Multi-Product Documentation",
"navigation": {
"products": [
{
"product": "API Platform",
"icon": "cloud",
"versions": [
{
"version": "v2",
"languages": [
{
"language": "English",
"tabs": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": [
{
"title": "Introduction",
"path": "api/v2/en/introduction"
}
]
}
]
}
]
},
{
"language": "Español",
"tabs": [
{
"tab": "Documentación",
"groups": [
{
"group": "Comenzar",
"pages": [
{
"title": "Introducción",
"path": "api/v2/es/introduccion"
}
]
}
]
}
]
}
]
}
]
},
{
"product": "Dashboard",
"icon": "layout-dashboard",
"tabs": [
{
"tab": "User Guide",
"pages": [
{
"title": "Overview",
"path": "dashboard/overview"
}
]
}
]
}
]
}
}
Example 4: View Nesting Patterns
Demonstrating the three standard UI template patterns.
{
"navigation": {
"tabs": [
{
"tab": "Documentation",
"dropdowns": [
{
"dropdown": "User Guide",
"dropdowns": [
{
"dropdown": "Getting Started",
"pages": [
{
"title": "Introduction",
"path": "intro"
}
]
}
]
}
]
}
]
}
}
{
"navigation": {
"dropdowns": [
{
"dropdown": "Platform",
"dropdowns": [
{
"dropdown": "Core Features",
"pages": [
{
"title": "Authentication",
"path": "auth"
}
]
}
]
}
]
}
}
{
"navigation": {
"tabs": [
{
"tab": "Documentation",
"dropdowns": [
{
"dropdown": "Features",
"dropdowns": [
{
"dropdown": "Advanced",
"pages": [
{
"title": "Webhooks",
"path": "webhooks"
}
]
}
]
}
]
}
]
}
}
Example 5: Complete Real-World Configuration
Full example with all features including dimensions, views, OpenAPI integration, and mixed content.
{
"name": "Paperguide Documentation",
"initialRoute": "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": "#3B82F6",
"heading": "#1a1a1a",
"text": "#374151"
},
"dark": {
"brand": "#60A5FA",
"heading": "#f2f2f2",
"text": "#c1c1c1"
}
},
"navbar": {
"actions": {
"primary": {
"title": "Get Started",
"link": "https://dashboard.paperguide.com/signup"
},
"links": [
{
"title": "Login",
"link": "https://dashboard.paperguide.com/login"
}
]
}
},
"navigation": {
"products": [
{
"product": "Paperguide",
"versions": [
{
"version": "v1",
"languages": [
{
"language": "English",
"tabs": [
{
"tab": "Getting Started",
"icon": "rocket",
"pages": [
{
"title": "Introduction",
"path": "introduction",
"icon": "home"
}
]
},
{
"tab": "Documentation",
"icon": "book",
"dropdowns": [
{
"dropdown": "Core Features",
"icon": "lightbulb",
"dropdowns": [
{
"dropdown": "Content Management",
"pages": [
{
"title": "Spaces",
"path": "spaces",
"icon": "folder"
},
{
"title": "Pages",
"path": "pages",
"icon": "file-text"
}
]
}
]
},
{
"dropdown": "Advanced Features",
"icon": "zap",
"pages": [
{
"title": "Webhooks",
"path": "webhooks",
"icon": "link"
}
]
}
]
},
{
"tab": "API Reference",
"icon": "code",
"groups": [
{
"group": "REST API",
"openapi": "api/openapi.yaml",
"pages": [
{
"title": "Authentication",
"path": "api/authentication"
}
]
}
]
}
]
}
]
}
]
}
]
},
"seo": {
"robots:index": true,
"robots:follow": true
}
}
Last updated 1 week ago