diff --git a/organize/navigation.mdx b/organize/navigation.mdx index 459b1661a..60ce8ee06 100644 --- a/organize/navigation.mdx +++ b/organize/navigation.mdx @@ -119,6 +119,265 @@ Use the `expanded` property to control the default state of a nested group in th } ``` +### Tags and labels + +Use tags to highlight navigation groups with status indicators or labels. Tags appear as small badges next to group names in the sidebar, helping users identify new features, beta functionality, deprecated content, or other important states. + +Tags are particularly useful for: +- Announcing new features or sections +- Indicating beta or experimental functionality +- Marking deprecated content +- Highlighting premium or enterprise features +- Drawing attention to recently updated sections + +#### Adding tags to groups + +Add a `tag` field to any navigation group. The tag text appears as a badge next to the group name. + +```json +{ + "navigation": { + "groups": [ + { + "group": "AI Features", + "icon": "sparkles", + "tag": "NEW", + "pages": ["ai/overview", "ai/chat", "ai/embeddings"] + }, + { + "group": "Experimental APIs", + "icon": "flask", + "tag": "BETA", + "pages": ["experimental/streaming", "experimental/webhooks"] + }, + { + "group": "Legacy SDK", + "icon": "box-archive", + "tag": "DEPRECATED", + "pages": ["legacy/v1", "legacy/migration"] + } + ] + } +} +``` + +#### Tags with nested groups + +Tags work with nested groups at any level of your navigation hierarchy. Each group can have its own tag. + +```json +{ + "navigation": { + "groups": [ + { + "group": "API Reference", + "icon": "code", + "pages": [ + "api/overview", + { + "group": "REST API", + "tag": "STABLE", + "pages": ["api/rest/users", "api/rest/projects"] + }, + { + "group": "GraphQL API", + "tag": "BETA", + "pages": ["api/graphql/queries", "api/graphql/mutations"] + }, + { + "group": "SOAP API", + "tag": "DEPRECATED", + "pages": ["api/soap/overview"] + } + ] + } + ] + } +} +``` + +#### Tags with tabs + +Add tags to tabs to highlight entire sections of your documentation. + +```json +{ + "navigation": { + "tabs": [ + { + "tab": "Documentation", + "icon": "book-open", + "pages": ["quickstart", "guides"] + }, + { + "tab": "API Reference", + "icon": "code", + "tag": "v2.0", + "groups": [ + { + "group": "Endpoints", + "pages": ["api/users", "api/projects"] + } + ] + }, + { + "tab": "Mobile SDK", + "icon": "mobile", + "tag": "PREVIEW", + "pages": ["mobile/ios", "mobile/android"] + } + ] + } +} +``` + +#### Tags with anchors + +Use tags on anchors to draw attention to specific sections in your sidebar navigation. + +```json +{ + "navigation": { + "anchors": [ + { + "anchor": "Documentation", + "icon": "book-open", + "pages": ["quickstart", "guides"] + }, + { + "anchor": "API v2", + "icon": "code", + "tag": "NEW", + "pages": ["api/overview", "api/endpoints"] + }, + { + "anchor": "Community", + "icon": "users", + "tag": "BETA", + "href": "https://community.example.com" + } + ] + } +} +``` + +#### Best practices for tags + +**Keep tags concise.** Use short, clear labels that fit comfortably next to group names. Ideal tags are 3-10 characters. + +**Use consistent terminology.** Establish a standard set of tags across your documentation: +- `NEW` - Recently added features or sections +- `BETA` - Features in beta testing +- `PREVIEW` - Early access features +- `DEPRECATED` - Features being phased out +- `UPDATED` - Recently updated content +- `PRO` or `ENTERPRISE` - Premium features + +**Use tags sparingly.** Too many tags reduce their effectiveness. Reserve tags for truly important status indicators. + +**Update tags regularly.** Remove `NEW` tags after features become established. Update `BETA` tags when features reach general availability. + +**Consider your audience.** Use tags that provide value to your users. Version numbers (`v2.0`) work well for API documentation, while status indicators (`BETA`) work better for feature documentation. + +#### Common tag examples + + + +```json Feature status +{ + "groups": [ + { + "group": "Core Features", + "tag": "STABLE", + "pages": ["features/auth", "features/storage"] + }, + { + "group": "Advanced Features", + "tag": "NEW", + "pages": ["features/ai", "features/analytics"] + }, + { + "group": "Experimental", + "tag": "BETA", + "pages": ["features/realtime", "features/edge"] + } + ] +} +``` + +```json Version indicators +{ + "groups": [ + { + "group": "API v3", + "tag": "LATEST", + "pages": ["v3/overview", "v3/endpoints"] + }, + { + "group": "API v2", + "tag": "v2.5", + "pages": ["v2/overview", "v2/endpoints"] + }, + { + "group": "API v1", + "tag": "EOL 2026", + "pages": ["v1/overview", "v1/migration"] + } + ] +} +``` + +```json Access levels +{ + "groups": [ + { + "group": "Free Features", + "pages": ["free/basics", "free/limits"] + }, + { + "group": "Pro Features", + "tag": "PRO", + "pages": ["pro/advanced", "pro/analytics"] + }, + { + "group": "Enterprise Features", + "tag": "ENTERPRISE", + "pages": ["enterprise/sso", "enterprise/audit"] + } + ] +} +``` + +```json Update notifications +{ + "groups": [ + { + "group": "Getting Started", + "pages": ["quickstart", "installation"] + }, + { + "group": "Authentication", + "tag": "UPDATED", + "pages": ["auth/oauth", "auth/jwt", "auth/api-keys"] + }, + { + "group": "Deployment", + "pages": ["deploy/cloud", "deploy/self-hosted"] + } + ] +} +``` + + + +#### Styling considerations + +Tags inherit your documentation's color scheme and automatically adapt to light and dark modes. The tag appearance is determined by your theme selection in `docs.json`. + +Tags are designed to be visually distinct without overwhelming the navigation. They use subtle styling that complements your theme's design while remaining clearly visible. + +For consistent branding across your documentation, use the same tag terminology in your page content when referring to tagged features. For example, if you tag a group as `BETA`, mention the beta status in the corresponding pages. + ## Tabs Tabs create distinct sections of your documentation with separate URL paths. Tabs create a horizontal navigation bar at the top of your documentation that lets users switch between sections.