776 lines
13 KiB
Markdown
776 lines
13 KiB
Markdown
# Navigation Structure and Organization Reference
|
|
|
|
Complete guide for organizing documentation with Mintlify's navigation system.
|
|
|
|
## Navigation Hierarchy
|
|
|
|
Mintlify supports complex navigation structures with multiple organizational patterns.
|
|
|
|
### Basic Navigation
|
|
|
|
Simple page groups:
|
|
|
|
```json
|
|
{
|
|
"navigation": [
|
|
{
|
|
"group": "Getting Started",
|
|
"pages": ["introduction", "quickstart", "installation"]
|
|
},
|
|
{
|
|
"group": "Core Concepts",
|
|
"pages": ["concepts/overview", "concepts/architecture"]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Group Properties
|
|
|
|
```json
|
|
{
|
|
"navigation": [
|
|
{
|
|
"group": "API Reference",
|
|
"icon": "code",
|
|
"tag": "New",
|
|
"expanded": false,
|
|
"pages": ["api/overview", "api/authentication"]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Properties:**
|
|
- `group` - Group title (required)
|
|
- `icon` - Icon from Font Awesome or Lucide
|
|
- `tag` - Badge text (e.g., "New", "Beta", "Deprecated")
|
|
- `expanded` - Expand group by default (boolean)
|
|
- `pages` - Array of page paths or nested groups (required)
|
|
|
|
## Pages
|
|
|
|
Reference MDX files without extension.
|
|
|
|
```json
|
|
{
|
|
"navigation": [
|
|
{
|
|
"group": "Guides",
|
|
"pages": [
|
|
"guides/getting-started",
|
|
"guides/authentication",
|
|
"guides/deployment"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**File mapping:**
|
|
- `"introduction"` → `/introduction.mdx`
|
|
- `"api/users"` → `/api/users.mdx`
|
|
- `"guides/quickstart"` → `/guides/quickstart.mdx`
|
|
|
|
## Nested Groups
|
|
|
|
Groups can contain nested groups (one level of nesting).
|
|
|
|
```json
|
|
{
|
|
"navigation": [
|
|
{
|
|
"group": "API Reference",
|
|
"pages": [
|
|
"api/overview",
|
|
{
|
|
"group": "Users",
|
|
"pages": ["api/users/list", "api/users/create", "api/users/get"]
|
|
},
|
|
{
|
|
"group": "Posts",
|
|
"pages": ["api/posts/list", "api/posts/create", "api/posts/get"]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Tabs
|
|
|
|
Organize documentation into major sections with tabs.
|
|
|
|
```json
|
|
{
|
|
"tabs": [
|
|
{
|
|
"name": "Documentation",
|
|
"url": "docs"
|
|
},
|
|
{
|
|
"name": "API Reference",
|
|
"url": "api",
|
|
"icon": "code"
|
|
},
|
|
{
|
|
"name": "Guides",
|
|
"url": "guides",
|
|
"icon": "book"
|
|
}
|
|
],
|
|
"navigation": [
|
|
{
|
|
"group": "Getting Started",
|
|
"pages": ["docs/introduction", "docs/quickstart"],
|
|
"tab": "Documentation"
|
|
},
|
|
{
|
|
"group": "Endpoints",
|
|
"pages": ["api/users", "api/posts"],
|
|
"tab": "API Reference"
|
|
},
|
|
{
|
|
"group": "Tutorials",
|
|
"pages": ["guides/auth", "guides/deploy"],
|
|
"tab": "Guides"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Tab properties:**
|
|
- `name` - Tab display name (required)
|
|
- `url` - URL path segment (required)
|
|
- `icon` - Tab icon
|
|
|
|
**Important:** Page paths must match tab URL:
|
|
- Tab `"url": "api"` → pages must start with `api/`
|
|
- Tab `"url": "docs"` → pages must start with `docs/`
|
|
|
|
## Menus
|
|
|
|
Dropdown menus within tabs for version/variant switching.
|
|
|
|
```json
|
|
{
|
|
"tabs": [
|
|
{
|
|
"name": "Documentation",
|
|
"url": "docs",
|
|
"menu": [
|
|
{
|
|
"name": "v2.0",
|
|
"url": "docs/v2"
|
|
},
|
|
{
|
|
"name": "v1.0",
|
|
"url": "docs/v1"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Anchors
|
|
|
|
Global navigation anchors for external links.
|
|
|
|
### Global Anchors
|
|
|
|
Appear in top-level navigation:
|
|
|
|
```json
|
|
{
|
|
"anchors": [
|
|
{
|
|
"name": "Community",
|
|
"icon": "discord",
|
|
"url": "https://discord.gg/example"
|
|
},
|
|
{
|
|
"name": "Blog",
|
|
"icon": "newspaper",
|
|
"url": "https://blog.example.com"
|
|
},
|
|
{
|
|
"name": "GitHub",
|
|
"icon": "github",
|
|
"url": "https://github.com/example/repo"
|
|
},
|
|
{
|
|
"name": "Status",
|
|
"icon": "activity",
|
|
"url": "https://status.example.com"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Local Anchors
|
|
|
|
Anchors within specific tabs:
|
|
|
|
```json
|
|
{
|
|
"tabs": [
|
|
{
|
|
"name": "API Reference",
|
|
"url": "api"
|
|
}
|
|
],
|
|
"anchors": [
|
|
{
|
|
"name": "API Status",
|
|
"icon": "activity",
|
|
"url": "https://status.example.com/api",
|
|
"tab": "API Reference"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Dropdowns
|
|
|
|
Top-level dropdown menus for resources.
|
|
|
|
```json
|
|
{
|
|
"dropdowns": [
|
|
{
|
|
"name": "Resources",
|
|
"icon": "book-open",
|
|
"items": [
|
|
{
|
|
"name": "Blog",
|
|
"url": "https://blog.example.com"
|
|
},
|
|
{
|
|
"name": "Changelog",
|
|
"url": "https://example.com/changelog"
|
|
},
|
|
{
|
|
"name": "Status Page",
|
|
"url": "https://status.example.com"
|
|
},
|
|
{
|
|
"name": "Support",
|
|
"url": "https://support.example.com"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "Tools",
|
|
"icon": "wrench",
|
|
"items": [
|
|
{
|
|
"name": "API Explorer",
|
|
"url": "https://api-explorer.example.com"
|
|
},
|
|
{
|
|
"name": "SDK Generator",
|
|
"url": "https://sdk.example.com"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Products
|
|
|
|
Partition documentation into separate products with independent navigation.
|
|
|
|
```json
|
|
{
|
|
"products": [
|
|
{
|
|
"name": "Product A",
|
|
"slug": "product-a",
|
|
"icon": "rocket"
|
|
},
|
|
{
|
|
"name": "Product B",
|
|
"slug": "product-b",
|
|
"icon": "star"
|
|
},
|
|
{
|
|
"name": "Product C",
|
|
"slug": "product-c",
|
|
"icon": "zap"
|
|
}
|
|
],
|
|
"navigation": [
|
|
{
|
|
"group": "Getting Started",
|
|
"pages": ["product-a/intro", "product-a/quickstart"],
|
|
"product": "product-a"
|
|
},
|
|
{
|
|
"group": "Getting Started",
|
|
"pages": ["product-b/intro", "product-b/setup"],
|
|
"product": "product-b"
|
|
},
|
|
{
|
|
"group": "Overview",
|
|
"pages": ["product-c/intro"],
|
|
"product": "product-c"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Users select product from top-level switcher. Each product has its own navigation tree.
|
|
|
|
## Versions
|
|
|
|
Manage multiple documentation versions.
|
|
|
|
```json
|
|
{
|
|
"versions": [
|
|
{
|
|
"name": "v3.0",
|
|
"slug": "v3"
|
|
},
|
|
{
|
|
"name": "v2.0",
|
|
"slug": "v2"
|
|
},
|
|
{
|
|
"name": "v1.0 (Legacy)",
|
|
"slug": "v1"
|
|
}
|
|
],
|
|
"navigation": [
|
|
{
|
|
"group": "Getting Started",
|
|
"pages": ["v3/introduction", "v3/installation"],
|
|
"version": "v3"
|
|
},
|
|
{
|
|
"group": "Getting Started",
|
|
"pages": ["v2/introduction", "v2/installation"],
|
|
"version": "v2"
|
|
},
|
|
{
|
|
"group": "Getting Started",
|
|
"pages": ["v1/introduction", "v1/installation"],
|
|
"version": "v1"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Users switch versions via dropdown. Each version maintains independent navigation.
|
|
|
|
## Languages
|
|
|
|
Multi-language documentation with i18n support.
|
|
|
|
```json
|
|
{
|
|
"languages": [
|
|
{
|
|
"name": "English",
|
|
"slug": "en"
|
|
},
|
|
{
|
|
"name": "Español",
|
|
"slug": "es"
|
|
},
|
|
{
|
|
"name": "Français",
|
|
"slug": "fr"
|
|
},
|
|
{
|
|
"name": "Deutsch",
|
|
"slug": "de"
|
|
},
|
|
{
|
|
"name": "日本語",
|
|
"slug": "ja"
|
|
},
|
|
{
|
|
"name": "中文",
|
|
"slug": "zh"
|
|
}
|
|
],
|
|
"navigation": [
|
|
{
|
|
"group": "Getting Started",
|
|
"pages": ["en/introduction", "en/quickstart"],
|
|
"language": "en"
|
|
},
|
|
{
|
|
"group": "Primeros Pasos",
|
|
"pages": ["es/introduccion", "es/inicio-rapido"],
|
|
"language": "es"
|
|
},
|
|
{
|
|
"group": "Commencer",
|
|
"pages": ["fr/introduction", "fr/demarrage"],
|
|
"language": "fr"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Supported Locales
|
|
|
|
28+ languages supported:
|
|
|
|
- `en` - English
|
|
- `es` - Español
|
|
- `fr` - Français
|
|
- `de` - Deutsch
|
|
- `it` - Italiano
|
|
- `pt` - Português
|
|
- `pt-BR` - Português (Brasil)
|
|
- `zh` - 中文
|
|
- `zh-TW` - 中文 (台灣)
|
|
- `ja` - 日本語
|
|
- `ko` - 한국어
|
|
- `ru` - Русский
|
|
- `ar` - العربية
|
|
- `hi` - हिन्दी
|
|
- `nl` - Nederlands
|
|
- `pl` - Polski
|
|
- `tr` - Türkçe
|
|
- `sv` - Svenska
|
|
- `da` - Dansk
|
|
- `no` - Norsk
|
|
- `fi` - Suomi
|
|
- `cs` - Čeština
|
|
- `hu` - Magyar
|
|
- `ro` - Română
|
|
- `th` - ไทย
|
|
- `vi` - Tiếng Việt
|
|
- `id` - Bahasa Indonesia
|
|
- `ms` - Bahasa Melayu
|
|
|
|
## Combining Products, Versions, and Languages
|
|
|
|
Complex navigation with all organizational patterns:
|
|
|
|
```json
|
|
{
|
|
"products": [
|
|
{
|
|
"name": "Platform API",
|
|
"slug": "api"
|
|
},
|
|
{
|
|
"name": "SDK",
|
|
"slug": "sdk"
|
|
}
|
|
],
|
|
"versions": [
|
|
{
|
|
"name": "v2.0",
|
|
"slug": "v2"
|
|
},
|
|
{
|
|
"name": "v1.0",
|
|
"slug": "v1"
|
|
}
|
|
],
|
|
"languages": [
|
|
{
|
|
"name": "English",
|
|
"slug": "en"
|
|
},
|
|
{
|
|
"name": "Español",
|
|
"slug": "es"
|
|
}
|
|
],
|
|
"navigation": [
|
|
{
|
|
"group": "Getting Started",
|
|
"pages": ["api/v2/en/intro"],
|
|
"product": "api",
|
|
"version": "v2",
|
|
"language": "en"
|
|
},
|
|
{
|
|
"group": "Primeros Pasos",
|
|
"pages": ["api/v2/es/intro"],
|
|
"product": "api",
|
|
"version": "v2",
|
|
"language": "es"
|
|
},
|
|
{
|
|
"group": "Getting Started",
|
|
"pages": ["sdk/v2/en/intro"],
|
|
"product": "sdk",
|
|
"version": "v2",
|
|
"language": "en"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Navigation Rules
|
|
|
|
### Nesting Rules
|
|
|
|
1. **One root-level element:** Choose tabs OR products OR simple groups
|
|
2. **One child type per level:** Groups can contain pages or groups, not both
|
|
3. **Max depth:** Limited nesting (typically 2-3 levels)
|
|
|
|
**Valid nesting:**
|
|
```json
|
|
{
|
|
"navigation": [
|
|
{
|
|
"group": "API",
|
|
"pages": [
|
|
"api/overview",
|
|
{
|
|
"group": "Resources",
|
|
"pages": ["api/users", "api/posts"]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Invalid nesting:**
|
|
```json
|
|
{
|
|
"navigation": [
|
|
{
|
|
"group": "API",
|
|
"pages": [
|
|
"api/overview",
|
|
{
|
|
"group": "Resources",
|
|
"pages": [
|
|
"api/users",
|
|
{
|
|
"group": "Nested too deep",
|
|
"pages": ["api/deep"]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Path Consistency
|
|
|
|
Pages must match their organizational context:
|
|
|
|
```json
|
|
{
|
|
"tabs": [
|
|
{"name": "Docs", "url": "docs"},
|
|
{"name": "API", "url": "api"}
|
|
],
|
|
"products": [
|
|
{"name": "Platform", "slug": "platform"}
|
|
],
|
|
"versions": [
|
|
{"name": "v2", "slug": "v2"}
|
|
],
|
|
"languages": [
|
|
{"name": "English", "slug": "en"}
|
|
],
|
|
"navigation": [
|
|
{
|
|
"group": "Guide",
|
|
"pages": ["api/platform/v2/en/introduction"],
|
|
"tab": "API",
|
|
"product": "platform",
|
|
"version": "v2",
|
|
"language": "en"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Path structure: `{tab}/{product}/{version}/{language}/{page}`
|
|
|
|
## Drilldown Navigation
|
|
|
|
Enable multi-level expandable navigation.
|
|
|
|
```json
|
|
{
|
|
"interaction": {
|
|
"drilldown": true
|
|
}
|
|
}
|
|
```
|
|
|
|
With drilldown enabled:
|
|
- Groups expand/collapse on click
|
|
- Deep nesting feels more navigable
|
|
- Better for complex documentation structures
|
|
|
|
## Icons
|
|
|
|
Use Font Awesome or Lucide icons in navigation.
|
|
|
|
### Font Awesome Icons
|
|
|
|
```json
|
|
{
|
|
"icon": {
|
|
"library": "fontawesome"
|
|
},
|
|
"navigation": [
|
|
{
|
|
"group": "Getting Started",
|
|
"icon": "rocket",
|
|
"pages": ["intro"]
|
|
},
|
|
{
|
|
"group": "API Reference",
|
|
"icon": "code",
|
|
"pages": ["api"]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Common Font Awesome icons:
|
|
- `rocket` - Getting started
|
|
- `book` - Documentation
|
|
- `code` - API reference
|
|
- `wrench` - Tools
|
|
- `star` - Features
|
|
- `shield` - Security
|
|
- `users` - Community
|
|
- `github` - GitHub
|
|
- `discord` - Discord
|
|
|
|
### Lucide Icons
|
|
|
|
```json
|
|
{
|
|
"icon": {
|
|
"library": "lucide"
|
|
},
|
|
"navigation": [
|
|
{
|
|
"group": "Guides",
|
|
"icon": "book-open",
|
|
"pages": ["guides"]
|
|
},
|
|
{
|
|
"group": "Components",
|
|
"icon": "layout",
|
|
"pages": ["components"]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Common Lucide icons:
|
|
- `book-open` - Guides
|
|
- `layout` - Components
|
|
- `terminal` - CLI
|
|
- `zap` - Quick start
|
|
- `shield-check` - Security
|
|
- `code-2` - API
|
|
|
|
## Complete Navigation Example
|
|
|
|
Full-featured navigation structure:
|
|
|
|
```json
|
|
{
|
|
"icon": {
|
|
"library": "fontawesome"
|
|
},
|
|
"tabs": [
|
|
{
|
|
"name": "Documentation",
|
|
"url": "docs"
|
|
},
|
|
{
|
|
"name": "API Reference",
|
|
"url": "api",
|
|
"icon": "code",
|
|
"menu": [
|
|
{"name": "v2.0", "url": "api/v2"},
|
|
{"name": "v1.0", "url": "api/v1"}
|
|
]
|
|
}
|
|
],
|
|
"anchors": [
|
|
{
|
|
"name": "Community",
|
|
"icon": "discord",
|
|
"url": "https://discord.gg/example"
|
|
},
|
|
{
|
|
"name": "GitHub",
|
|
"icon": "github",
|
|
"url": "https://github.com/example/repo"
|
|
}
|
|
],
|
|
"dropdowns": [
|
|
{
|
|
"name": "Resources",
|
|
"icon": "book-open",
|
|
"items": [
|
|
{"name": "Blog", "url": "https://blog.example.com"},
|
|
{"name": "Status", "url": "https://status.example.com"}
|
|
]
|
|
}
|
|
],
|
|
"navigation": [
|
|
{
|
|
"group": "Getting Started",
|
|
"icon": "rocket",
|
|
"pages": ["docs/introduction", "docs/quickstart"],
|
|
"tab": "Documentation"
|
|
},
|
|
{
|
|
"group": "Core Concepts",
|
|
"icon": "book",
|
|
"expanded": true,
|
|
"pages": [
|
|
"docs/concepts/overview",
|
|
{
|
|
"group": "Advanced",
|
|
"pages": ["docs/concepts/architecture", "docs/concepts/security"]
|
|
}
|
|
],
|
|
"tab": "Documentation"
|
|
},
|
|
{
|
|
"group": "Authentication",
|
|
"icon": "shield",
|
|
"pages": ["api/v2/auth/overview", "api/v2/auth/oauth"],
|
|
"tab": "API Reference"
|
|
},
|
|
{
|
|
"group": "Endpoints",
|
|
"icon": "code",
|
|
"pages": [
|
|
{
|
|
"group": "Users",
|
|
"pages": ["api/v2/users/list", "api/v2/users/create"]
|
|
},
|
|
{
|
|
"group": "Posts",
|
|
"pages": ["api/v2/posts/list", "api/v2/posts/create"]
|
|
}
|
|
],
|
|
"tab": "API Reference"
|
|
}
|
|
],
|
|
"interaction": {
|
|
"drilldown": true
|
|
}
|
|
}
|
|
```
|