diff --git a/navigation.mdx b/navigation.mdx index bbc801c64..d74c71714 100644 --- a/navigation.mdx +++ b/navigation.mdx @@ -247,6 +247,418 @@ In the `navigation` object, `anchors` is an array where each entry is an object } ``` +### Complex anchors with tabs + +For more sophisticated navigation structures, you can combine anchors with tabs to create multi-level hierarchies. This is particularly useful for large documentation sites with distinct product areas or user types. + + + +```json Multi-product documentation +{ + "navigation": { + "anchors": [ + { + "anchor": "Platform", + "icon": "layers", + "tabs": [ + { + "tab": "Getting started", + "icon": "rocket", + "groups": [ + { + "group": "Quick start", + "pages": [ + "platform/quickstart", + "platform/installation", + "platform/first-project" + ] + }, + { + "group": "Configuration", + "pages": [ + "platform/config/environment", + "platform/config/authentication", + "platform/config/permissions" + ] + } + ] + }, + { + "tab": "API reference", + "icon": "square-terminal", + "groups": [ + { + "group": "Core endpoints", + "openapi": "/openapi/platform-core.json", + "pages": [ + "GET /projects", + "POST /projects", + "GET /projects/{id}" + ] + }, + { + "group": "Analytics", + "openapi": "/openapi/platform-analytics.json", + "pages": [ + "GET /analytics/events", + "POST /analytics/track" + ] + } + ] + } + ] + }, + { + "anchor": "SDKs", + "icon": "code", + "tabs": [ + { + "tab": "JavaScript", + "icon": "brand-javascript", + "groups": [ + { + "group": "Getting started", + "pages": [ + "sdks/javascript/installation", + "sdks/javascript/quickstart", + "sdks/javascript/configuration" + ] + }, + { + "group": "Advanced", + "pages": [ + "sdks/javascript/authentication", + "sdks/javascript/error-handling", + "sdks/javascript/webhooks" + ] + } + ] + }, + { + "tab": "Python", + "icon": "brand-python", + "groups": [ + { + "group": "Getting started", + "pages": [ + "sdks/python/installation", + "sdks/python/quickstart", + "sdks/python/configuration" + ] + }, + { + "group": "Advanced", + "pages": [ + "sdks/python/async-support", + "sdks/python/custom-clients", + "sdks/python/testing" + ] + } + ] + }, + { + "tab": "Go", + "icon": "brand-golang", + "groups": [ + { + "group": "Getting started", + "pages": [ + "sdks/go/installation", + "sdks/go/quickstart" + ] + } + ] + } + ] + } + ], + "global": { + "anchors": [ + { + "anchor": "Community", + "icon": "users", + "href": "https://discord.gg/community" + }, + { + "anchor": "Status", + "icon": "activity", + "href": "https://status.example.com" + } + ] + } + } +} +``` + +```json Developer portal with role-based navigation +{ + "navigation": { + "anchors": [ + { + "anchor": "Developers", + "icon": "code", + "tabs": [ + { + "tab": "REST API", + "icon": "api", + "menu": [ + { + "item": "Authentication", + "icon": "shield-check", + "pages": [ + "api/auth/overview", + "api/auth/oauth", + "api/auth/api-keys" + ] + }, + { + "item": "Core resources", + "icon": "database", + "groups": [ + { + "group": "Users", + "openapi": "/openapi/users.json", + "pages": [ + "GET /users", + "POST /users", + "GET /users/{id}", + "PUT /users/{id}" + ] + }, + { + "group": "Organizations", + "openapi": "/openapi/orgs.json", + "pages": [ + "GET /organizations", + "POST /organizations" + ] + } + ] + } + ] + }, + { + "tab": "GraphQL", + "icon": "brand-graphql", + "groups": [ + { + "group": "Getting started", + "pages": [ + "graphql/overview", + "graphql/authentication", + "graphql/explorer" + ] + }, + { + "group": "Schema reference", + "pages": [ + "graphql/queries", + "graphql/mutations", + "graphql/subscriptions" + ] + } + ] + }, + { + "tab": "Webhooks", + "icon": "webhook", + "groups": [ + { + "group": "Setup", + "pages": [ + "webhooks/getting-started", + "webhooks/security", + "webhooks/testing" + ] + }, + { + "group": "Event types", + "pages": [ + "webhooks/user-events", + "webhooks/payment-events", + "webhooks/system-events" + ] + } + ] + } + ] + }, + { + "anchor": "Partners", + "icon": "handshake", + "tabs": [ + { + "tab": "Integration guide", + "icon": "puzzle", + "groups": [ + { + "group": "Getting started", + "pages": [ + "partners/overview", + "partners/onboarding", + "partners/certification" + ] + }, + { + "group": "Technical integration", + "pages": [ + "partners/oauth-flow", + "partners/scoped-permissions", + "partners/rate-limits" + ] + } + ] + }, + { + "tab": "Marketplace", + "icon": "store", + "groups": [ + { + "group": "Publishing", + "pages": [ + "partners/marketplace/submission", + "partners/marketplace/guidelines", + "partners/marketplace/review-process" + ] + } + ] + } + ] + } + ] + } +} +``` + +```json Enterprise documentation structure +{ + "navigation": { + "anchors": [ + { + "anchor": "Administration", + "icon": "settings", + "tabs": [ + { + "tab": "User management", + "icon": "users", + "groups": [ + { + "group": "Setup", + "pages": [ + "admin/users/sso-configuration", + "admin/users/directory-sync", + "admin/users/provisioning" + ] + }, + { + "group": "Permissions", + "pages": [ + "admin/users/roles", + "admin/users/custom-permissions", + "admin/users/audit-logs" + ] + } + ] + }, + { + "tab": "Security", + "icon": "shield", + "groups": [ + { + "group": "Compliance", + "pages": [ + "admin/security/soc2", + "admin/security/gdpr", + "admin/security/hipaa" + ] + }, + { + "group": "Network security", + "pages": [ + "admin/security/ip-allowlisting", + "admin/security/vpn-setup", + "admin/security/certificate-management" + ] + } + ] + }, + { + "tab": "Analytics", + "icon": "chart-bar", + "groups": [ + { + "group": "Usage metrics", + "pages": [ + "admin/analytics/dashboard", + "admin/analytics/api-usage", + "admin/analytics/user-activity" + ] + }, + { + "group": "Reporting", + "pages": [ + "admin/analytics/custom-reports", + "admin/analytics/scheduled-exports", + "admin/analytics/data-retention" + ] + } + ] + } + ] + }, + { + "anchor": "End users", + "icon": "user", + "tabs": [ + { + "tab": "Getting started", + "icon": "play", + "pages": [ + "users/onboarding", + "users/first-steps", + "users/account-setup" + ] + }, + { + "tab": "Features", + "icon": "sparkles", + "groups": [ + { + "group": "Core features", + "pages": [ + "users/features/dashboard", + "users/features/projects", + "users/features/collaboration" + ] + }, + { + "group": "Advanced features", + "pages": [ + "users/features/automation", + "users/features/integrations", + "users/features/custom-workflows" + ] + } + ] + } + ] + } + ], + "global": { + "anchors": [ + { + "anchor": "Support", + "icon": "help-circle", + "href": "https://support.example.com" + } + ] + } + } +} +``` + + + For anchors that direct to external links only, use the `global` keyword. Anchors in a `global` object must have an `href` field and cannot point to a relative path. Global anchors are particularly useful for linking to resources that are not part of your documentation, but should be readily accessible to your users like a blog or support portal