From b18458cb1bd3b2d25a3adb7851825f381fa511e7 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 12 Feb 2026 18:57:31 +0000 Subject: [PATCH] Update organize/settings.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- organize/settings.mdx | 766 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 766 insertions(+) diff --git a/organize/settings.mdx b/organize/settings.mdx index d7b1f908c..2d12a1d46 100644 --- a/organize/settings.mdx +++ b/organize/settings.mdx @@ -1119,6 +1119,772 @@ This section contains the full reference for the `docs.json` file. +## Common docs.json patterns and examples + +This section provides complete, working examples of `docs.json` files for different use cases. Each example includes comments explaining the structure and purpose of each section. + +### Simple documentation site + +A minimal configuration for a straightforward documentation site with basic navigation and styling. + +```json docs.json +{ + // Schema reference enables autocomplete and validation in your editor + "$schema": "https://mintlify.com/docs.json", + + // Required: Choose a theme that matches your brand + "theme": "mint", + + // Required: Your project name appears in the browser tab and navigation + "name": "Simple Docs", + + // Required: Primary brand color for links, buttons, and accents + "colors": { + "primary": "#0D9373" + }, + + // Optional: Improve SEO with a clear description + "description": "Documentation for our product", + + // Required: Basic navigation structure with groups + "navigation": { + "groups": [ + { + "group": "Getting started", + "pages": [ + "introduction", + "quickstart", + "installation" + ] + }, + { + "group": "Guides", + "pages": [ + "guides/authentication", + "guides/configuration", + "guides/deployment" + ] + }, + { + "group": "Resources", + "pages": [ + "faq", + "support", + "changelog" + ] + } + ] + }, + + // Optional: Add your logo for branding + "logo": { + "light": "/logo-light.svg", + "dark": "/logo-dark.svg" + }, + + // Optional: Add a favicon + "favicon": "/favicon.png" +} +``` + +**Key features:** +- Minimal required fields only +- Simple group-based navigation +- Single primary color +- Basic branding with logo and favicon + +### API documentation with OpenAPI + +A configuration optimized for API documentation with interactive playground and auto-generated endpoints from OpenAPI specifications. + +```json docs.json +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "maple", + "name": "API Documentation", + "colors": { + "primary": "#3B82F6", + "light": "#60A5FA", + "dark": "#1E40AF" + }, + + // Navigation with tabs separates guides from API reference + "navigation": { + "tabs": [ + { + "tab": "Documentation", + "icon": "book-open", + "groups": [ + { + "group": "Getting started", + "pages": [ + "introduction", + "authentication", + "rate-limits" + ] + }, + { + "group": "Guides", + "pages": [ + "guides/making-requests", + "guides/error-handling", + "guides/webhooks" + ] + } + ] + }, + { + "tab": "API Reference", + "icon": "square-terminal", + "groups": [ + { + "group": "Endpoints", + // OpenAPI specification auto-generates endpoint pages + "openapi": "/openapi.json", + "pages": [ + "api-reference/overview", + // Reference specific endpoints from your OpenAPI spec + "GET /users", + "POST /users", + "GET /users/{id}", + "PUT /users/{id}", + "DELETE /users/{id}", + "GET /products", + "POST /products" + ] + } + ] + } + ] + }, + + // API configuration for interactive playground + "api": { + // Point to your OpenAPI specification file + "openapi": "/openapi.json", + + // Playground settings for testing API calls + "playground": { + "display": "interactive", // Show interactive request builder + "proxy": true // Route requests through proxy for CORS + }, + + // Configure code examples in multiple languages + "examples": { + "languages": ["bash", "javascript", "python", "go"], + "defaults": "required", // Show only required parameters by default + "prefill": true, // Auto-fill examples from OpenAPI spec + "autogenerate": true // Generate code samples automatically + }, + + // Expand all parameters by default for easier reference + "params": { + "expanded": "all" + } + }, + + // Add navbar links to GitHub and community + "navbar": { + "links": [ + { + "type": "github", + "href": "https://github.com/your-org/your-repo" + } + ], + "primary": { + "type": "button", + "label": "Get API Key", + "href": "https://app.example.com/api-keys" + } + }, + + // Footer with social links and resources + "footer": { + "socials": { + "github": "https://github.com/your-org", + "x": "https://x.com/yourcompany", + "discord": "https://discord.gg/your-server" + } + } +} +``` + +**Key features:** +- Tab-based navigation separating guides from API reference +- OpenAPI integration for auto-generated endpoint documentation +- Interactive API playground with multiple language examples +- Customized code sample languages +- Call-to-action button in navbar + +### Multi-language site + +A configuration for documentation available in multiple languages with language-specific navigation and content. + +```json docs.json +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "willow", + "name": "Multi-Language Docs", + "colors": { + "primary": "#8B5CF6" + }, + + // Language-based navigation with separate content for each language + "navigation": { + // Global anchors appear across all language versions + "global": { + "anchors": [ + { + "anchor": "Community", + "icon": "users", + "href": "https://community.example.com" + }, + { + "anchor": "Blog", + "icon": "newspaper", + "href": "https://blog.example.com" + } + ] + }, + + // Define navigation for each supported language + "languages": [ + { + // English version (default) + "language": "en", + "groups": [ + { + "group": "Getting started", + "pages": [ + "en/introduction", + "en/quickstart", + "en/installation" + ] + }, + { + "group": "Core concepts", + "pages": [ + "en/concepts/authentication", + "en/concepts/data-models", + "en/concepts/permissions" + ] + }, + { + "group": "API Reference", + "pages": [ + "en/api/overview", + "en/api/endpoints" + ] + } + ] + }, + { + // Spanish version + "language": "es", + "groups": [ + { + "group": "Comenzando", + "pages": [ + "es/introduction", + "es/quickstart", + "es/installation" + ] + }, + { + "group": "Conceptos básicos", + "pages": [ + "es/concepts/authentication", + "es/concepts/data-models", + "es/concepts/permissions" + ] + }, + { + "group": "Referencia de API", + "pages": [ + "es/api/overview", + "es/api/endpoints" + ] + } + ] + }, + { + // French version + "language": "fr", + "groups": [ + { + "group": "Commencer", + "pages": [ + "fr/introduction", + "fr/quickstart", + "fr/installation" + ] + }, + { + "group": "Concepts de base", + "pages": [ + "fr/concepts/authentication", + "fr/concepts/data-models", + "fr/concepts/permissions" + ] + }, + { + "group": "Référence API", + "pages": [ + "fr/api/overview", + "fr/api/endpoints" + ] + } + ] + }, + { + // Japanese version + "language": "jp", + "groups": [ + { + "group": "はじめに", + "pages": [ + "jp/introduction", + "jp/quickstart", + "jp/installation" + ] + }, + { + "group": "基本概念", + "pages": [ + "jp/concepts/authentication", + "jp/concepts/data-models", + "jp/concepts/permissions" + ] + }, + { + "group": "APIリファレンス", + "pages": [ + "jp/api/overview", + "jp/api/endpoints" + ] + } + ] + } + ] + }, + + // Logo and branding + "logo": { + "light": "/logo-light.svg", + "dark": "/logo-dark.svg" + } +} +``` + +**Key features:** +- Language switcher dropdown for easy navigation between translations +- Global anchors that appear across all language versions +- Separate navigation structure for each language +- Organized file structure with language-specific directories (en/, es/, fr/, jp/) +- Support for 25+ languages including RTL languages like Arabic + +**Supported languages:** ar, cn, cs, de, en, es, fr, he, hi, id, it, jp, ko, lv, nl, no, pl, pt-BR, ro, ru, sv, tr, ua, uz, vi, zh-Hant + +### Versioned documentation + +A configuration for maintaining multiple versions of documentation with a version switcher. + +```json docs.json +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "palm", + "name": "Versioned Docs", + "colors": { + "primary": "#10B981", + "light": "#34D399", + "dark": "#059669" + }, + + // Version-based navigation allows users to switch between versions + "navigation": { + "versions": [ + { + // Latest version (v3.0) + "version": "3.0", + "tabs": [ + { + "tab": "Documentation", + "icon": "book-open", + "groups": [ + { + "group": "Getting started", + "pages": [ + "v3/introduction", + "v3/quickstart", + "v3/migration-from-v2" + ] + }, + { + "group": "Core features", + "pages": [ + "v3/features/authentication", + "v3/features/real-time-sync", + "v3/features/advanced-queries" + ] + }, + { + "group": "Guides", + "pages": [ + "v3/guides/deployment", + "v3/guides/scaling", + "v3/guides/monitoring" + ] + } + ] + }, + { + "tab": "API Reference", + "icon": "square-terminal", + "groups": [ + { + "group": "REST API", + "openapi": "/openapi-v3.json", + "pages": [ + "v3/api/overview", + "GET /v3/users", + "POST /v3/users", + "GET /v3/projects" + ] + } + ] + } + ] + }, + { + // Previous stable version (v2.0) + "version": "2.0", + "tabs": [ + { + "tab": "Documentation", + "icon": "book-open", + "groups": [ + { + "group": "Getting started", + "pages": [ + "v2/introduction", + "v2/quickstart", + "v2/installation" + ] + }, + { + "group": "Core features", + "pages": [ + "v2/features/authentication", + "v2/features/data-sync" + ] + }, + { + "group": "Guides", + "pages": [ + "v2/guides/deployment", + "v2/guides/best-practices" + ] + } + ] + }, + { + "tab": "API Reference", + "icon": "square-terminal", + "groups": [ + { + "group": "REST API", + "openapi": "/openapi-v2.json", + "pages": [ + "v2/api/overview", + "GET /v2/users", + "POST /v2/users" + ] + } + ] + } + ] + }, + { + // Legacy version (v1.0) + "version": "1.0", + "groups": [ + { + "group": "Documentation", + "pages": [ + "v1/introduction", + "v1/quickstart", + "v1/api-reference" + ] + } + ] + } + ] + }, + + // Banner to notify users about version status + "banner": { + "content": "📢 Version 3.0 is now available! Check out the [migration guide](/v3/migration-from-v2) to upgrade.", + "dismissible": true + }, + + // Navbar with version-specific links + "navbar": { + "links": [ + { + "type": "github", + "href": "https://github.com/your-org/your-repo" + } + ], + "primary": { + "type": "button", + "label": "Get Started", + "href": "https://app.example.com/signup" + } + } +} +``` + +**Key features:** +- Version switcher dropdown for easy navigation between versions +- Separate OpenAPI specifications for each API version +- Version-specific navigation structures +- Migration guides between versions +- Banner to highlight latest version +- Organized file structure with version directories (v1/, v2/, v3/) + +### Troubleshooting + +Common issues when configuring `docs.json` and how to resolve them. + +#### JSON syntax errors + +**Problem:** Your documentation fails to build with a JSON parsing error. + +**Common causes:** +- Missing or extra commas +- Unmatched brackets or braces +- Comments in JSON (not supported in standard JSON) +- Trailing commas after the last item in an array or object + +**Solution:** +```json +// ❌ Invalid: Trailing comma +{ + "name": "My Docs", + "theme": "mint", // <- Remove this comma +} + +// ✅ Valid: No trailing comma +{ + "name": "My Docs", + "theme": "mint" +} + +// ❌ Invalid: Missing comma +{ + "name": "My Docs" + "theme": "mint" +} + +// ✅ Valid: Comma between properties +{ + "name": "My Docs", + "theme": "mint" +} +``` + +**Validation tip:** Use a JSON validator like [JSONLint](https://jsonlint.com/) to check your syntax before deploying. + +#### Navigation pages not found + +**Problem:** Pages appear in navigation but show 404 errors when clicked. + +**Common causes:** +- File path in navigation doesn't match actual file location +- Missing `.mdx` extension in file name (don't include extension in navigation) +- Incorrect directory structure + +**Solution:** +```json +// File structure: +// docs/ +// guides/ +// getting-started.mdx +// api/ +// overview.mdx + +// ❌ Invalid: Including file extension +{ + "navigation": { + "pages": ["guides/getting-started.mdx"] + } +} + +// ❌ Invalid: Wrong path +{ + "navigation": { + "pages": ["getting-started"] // File is in guides/ directory + } +} + +// ✅ Valid: Correct path without extension +{ + "navigation": { + "pages": ["guides/getting-started"] + } +} +``` + +#### OpenAPI endpoints not generating + +**Problem:** OpenAPI specification is configured but endpoint pages don't appear. + +**Common causes:** +- Invalid OpenAPI specification file +- Incorrect file path to OpenAPI spec +- Missing endpoint references in navigation +- OpenAPI file not in repository root or accessible path + +**Solution:** +```json +// ❌ Invalid: Wrong path +{ + "api": { + "openapi": "openapi.json" // File doesn't exist at root + } +} + +// ✅ Valid: Correct path with leading slash +{ + "api": { + "openapi": "/api-specs/openapi.json" + } +} + +// ✅ Valid: Reference specific endpoints +{ + "navigation": { + "groups": [ + { + "group": "API Reference", + "openapi": "/openapi.json", + "pages": [ + "api/overview", + "GET /users", // Must match operationId or path in spec + "POST /users", + "GET /users/{id}" + ] + } + ] + } +} +``` + +**Validation tip:** Validate your OpenAPI specification using [Swagger Editor](https://editor.swagger.io/) before adding it to your docs. + +#### Colors not applying correctly + +**Problem:** Custom colors don't appear or look different than expected. + +**Common causes:** +- Invalid hex color format +- Missing `#` prefix +- Using RGB or color names instead of hex codes + +**Solution:** +```json +// ❌ Invalid: Missing # prefix +{ + "colors": { + "primary": "FF0000" + } +} + +// ❌ Invalid: Using RGB format +{ + "colors": { + "primary": "rgb(255, 0, 0)" + } +} + +// ✅ Valid: Hex code with # prefix +{ + "colors": { + "primary": "#FF0000" + } +} + +// ✅ Valid: 3-digit hex shorthand +{ + "colors": { + "primary": "#F00" + } +} +``` + +#### Schema validation errors + +**Problem:** Editor shows validation errors or autocomplete doesn't work. + +**Solution:** Always include the schema reference at the top of your `docs.json`: + +```json +{ + "$schema": "https://mintlify.com/docs.json", + // ... rest of your configuration +} +``` + +This enables: +- Real-time validation in VS Code and other editors +- Autocomplete suggestions for properties +- Inline documentation for each field +- Error detection before deployment + +#### Navigation structure validation + +**Problem:** Navigation appears broken or pages are in wrong order. + +**Best practices:** +1. **Use consistent nesting:** Choose one primary navigation pattern (tabs, groups, anchors, or dropdowns) at the root level +2. **Avoid deep nesting:** Keep navigation hierarchy to 3-4 levels maximum for better UX +3. **Test navigation paths:** Ensure all pages are reachable from the navigation +4. **Use meaningful names:** Group and page names should be clear and descriptive + +```json +// ✅ Good: Clear hierarchy with consistent structure +{ + "navigation": { + "tabs": [ + { + "tab": "Documentation", + "groups": [ + { + "group": "Getting started", + "pages": ["intro", "quickstart"] + }, + { + "group": "Advanced", + "pages": ["advanced/config", "advanced/api"] + } + ] + } + ] + } +} +``` + +#### Validating your docs.json + +To ensure your `docs.json` is valid before deploying: + +1. **Use the schema reference:** Add `"$schema": "https://mintlify.com/docs.json"` at the top of your file +2. **Check JSON syntax:** Use [JSONLint](https://jsonlint.com/) or your editor's built-in validator +3. **Test locally:** Run `mint dev` to preview your documentation locally +4. **Verify file paths:** Ensure all referenced files (pages, images, OpenAPI specs) exist +5. **Check required fields:** Confirm `theme`, `name`, `colors.primary`, and `navigation` are present +6. **Review navigation structure:** Ensure all pages are accessible and properly nested + ## Examples