diff --git a/settings.mdx b/settings.mdx index c3af9720..e14c136e 100644 --- a/settings.mdx +++ b/settings.mdx @@ -779,6 +779,241 @@ This section contains the full reference for the docs.json file. +## Example Configuration + +Here's an example of a `docs.json` file showcasing various configuration options: + +```json +{ + "$schema": "https://mintlify.com/docs.json", + "name": "Acme API Documentation", + "description": "Complete API documentation for Acme's developer platform", + "theme": "mint", + "logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg", + "href": "https://acme.com" + }, + "favicon": "/favicon.png", + "colors": { + "primary": "#0D9373", + "light": "#07C983", + "dark": "#0D9373" + }, + "styling": { + "eyebrows": "breadcrumbs", + "codeblocks": "dark" + }, + "icons": { + "library": "lucide" + }, + "fonts": { + "family": "Inter", + "weight": 400, + "heading": { + "family": "Inter", + "weight": 600 + } + }, + "appearance": { + "default": "system", + "strict": false + }, + "background": { + "decoration": "gradient", + "color": { + "light": "#f8fafc", + "dark": "#0f172a" + } + }, + "navbar": { + "links": [ + { + "label": "Blog", + "href": "https://acme.com/blog", + "icon": "newspaper" + }, + { + "label": "Community", + "href": "https://discord.gg/acme", + "icon": "users" + } + ], + "primary": { + "type": "github", + "href": "https://github.com/acme/api" + } + }, + "navigation": { + "global": { + "languages": [ + { + "language": "en", + "default": true, + "href": "/" + }, + { + "language": "es", + "href": "/es" + } + ], + "versions": [ + { + "version": "v2.0", + "default": true, + "href": "/" + }, + { + "version": "v1.0", + "href": "/v1" + } + ] + }, + "tabs": [ + { + "tab": "Getting Started", + "pages": [ + "introduction", + "quickstart", + "authentication" + ] + }, + { + "tab": "API Reference", + "pages": [ + { + "group": "Users", + "pages": [ + "api-reference/users/create", + "api-reference/users/get", + "api-reference/users/update", + "api-reference/users/delete" + ] + }, + { + "group": "Projects", + "pages": [ + "api-reference/projects/list", + "api-reference/projects/create", + "api-reference/projects/get" + ] + } + ] + }, + { + "tab": "Guides", + "pages": [ + "guides/webhooks", + "guides/rate-limiting", + "guides/error-handling" + ] + } + ] + }, + "footer": { + "socials": { + "x": "https://x.com/acme", + "github": "https://github.com/acme", + "linkedin": "https://linkedin.com/company/acme", + "discord": "https://discord.gg/acme" + }, + "links": [ + { + "header": "Product", + "items": [ + { + "label": "Features", + "href": "https://acme.com/features" + }, + { + "label": "Pricing", + "href": "https://acme.com/pricing" + } + ] + }, + { + "header": "Resources", + "items": [ + { + "label": "Blog", + "href": "https://acme.com/blog" + }, + { + "label": "Status", + "href": "https://status.acme.com" + } + ] + } + ] + }, + "banner": { + "content": "🎉 API v2.0 is now live! [View the migration guide →](/migration)", + "dismissible": true + }, + "api": { + "openapi": [ + "https://api.acme.com/openapi.json", + "/openapi/users.json" + ], + "playground": { + "display": "interactive", + "proxy": true + }, + "examples": { + "languages": ["javascript", "python", "curl", "go"], + "defaults": "required" + }, + "mdx": { + "auth": { + "method": "bearer", + "name": "Authorization" + }, + "server": "https://api.acme.com" + } + }, + "seo": { + "indexing": "navigable", + "metatags": { + "og:site_name": "Acme API Documentation", + "twitter:site": "@acme" + } + }, + "search": { + "prompt": "Search documentation..." + }, + "integrations": { + "ga4": { + "measurementId": "G-XXXXXXXXXX" + }, + "intercom": { + "appId": "abcd1234" + }, + "posthog": { + "apiKey": "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", + "apiHost": "https://app.posthog.com" + } + }, + "contextual": { + "options": ["copy", "chatgpt", "claude"] + }, + "redirects": [ + { + "source": "/old-docs/:path*", + "destination": "/new-docs/:path*", + "permanent": true + } + ] +} +``` + +This example demonstrates: +- **Theme & Branding**: Custom colors, fonts, and logo configuration +- **Navigation**: Multi-tab structure with grouped pages and global options +- **API Integration**: OpenAPI specs, playground settings, and authentication +- **SEO & Analytics**: Search engine optimization and tracking integrations +- **User Experience**: Banners, contextual menus, and footer links +- **Internationalization**: Multi-language and versioning support + ## Validation It is advised to include the following schema reference at the top of your docs.json file to ensure proper validation while editing: