diff --git a/organize/navigation.mdx b/organize/navigation.mdx index df6913b9c..036a99dcd 100644 --- a/organize/navigation.mdx +++ b/organize/navigation.mdx @@ -119,6 +119,174 @@ Use the `expanded` property to control the default state of a nested group in th } ``` +### Tags and labels + +Use tags to highlight important navigation items and draw attention to new, updated, or deprecated content. Tags appear as small labels next to navigation group names in the sidebar. + +Navigation groups with tags displayed in the sidebar. + +Navigation groups with tags displayed in the sidebar. + +#### Adding tags to navigation groups + +Add the `tag` field to any navigation group to display a label. Tags work with all navigation elements that support groups, including tabs, anchors, dropdowns, and products. + +```json +{ + "navigation": { + "groups": [ + { + "group": "Getting started", + "icon": "play", + "tag": "NEW", + "pages": ["quickstart", "installation"] + }, + { + "group": "API v2", + "icon": "code", + "tag": "BETA", + "pages": ["api/v2/overview", "api/v2/endpoints"] + }, + { + "group": "Legacy API", + "icon": "archive", + "tag": "DEPRECATED", + "pages": ["api/v1/overview"] + } + ] + } +} +``` + +#### Tag best practices + +Use tags strategically to guide users to the most relevant content: + +- **NEW**: Highlight recently added features or documentation sections +- **BETA**: Indicate features in testing or early access +- **UPDATED**: Draw attention to recently revised content +- **DEPRECATED**: Mark outdated features that will be removed +- **PREVIEW**: Show experimental features available for early feedback +- **PRO** or **ENTERPRISE**: Denote premium or tier-specific features + +Keep tag text short and descriptive. Tags longer than 12 characters may be truncated on smaller screens. + +#### Tags in different navigation contexts + +Tags work consistently across all navigation elements: + + + +```json Groups with tags +{ + "navigation": { + "groups": [ + { + "group": "Core features", + "tag": "STABLE", + "pages": ["features/auth", "features/storage"] + }, + { + "group": "Experimental", + "tag": "PREVIEW", + "pages": ["features/ai", "features/realtime"] + } + ] + } +} +``` + +```json Tabs with tagged groups +{ + "navigation": { + "tabs": [ + { + "tab": "Documentation", + "icon": "book-open", + "groups": [ + { + "group": "Getting started", + "tag": "NEW", + "pages": ["quickstart"] + }, + { + "group": "Advanced guides", + "pages": ["deployment", "scaling"] + } + ] + } + ] + } +} +``` + +```json Anchors with tagged groups +{ + "navigation": { + "anchors": [ + { + "anchor": "API Reference", + "icon": "code", + "groups": [ + { + "group": "REST API v3", + "tag": "LATEST", + "pages": ["api/v3/users", "api/v3/projects"] + }, + { + "group": "REST API v2", + "tag": "DEPRECATED", + "pages": ["api/v2/users", "api/v2/projects"] + } + ] + } + ] + } +} +``` + +```json Nested groups with tags +{ + "navigation": { + "groups": [ + { + "group": "Platform", + "pages": [ + { + "group": "Authentication", + "tag": "UPDATED", + "pages": ["auth/oauth", "auth/jwt"] + }, + { + "group": "Webhooks", + "tag": "BETA", + "pages": ["webhooks/setup", "webhooks/events"] + } + ] + } + ] + } +} +``` + + + +#### Styling considerations + +Tags inherit your documentation's primary color scheme by default. The appearance adapts automatically to light and dark modes based on your theme configuration. + + + Tags are purely visual indicators and do not affect navigation functionality or page accessibility. Users can still access all pages within tagged groups normally. + + ## 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.