Add comprehensive tag documentation to navigation

organize/navigation.mdx

@@ -98,11 +98,11 @@
 
 Use the `expanded` property to control the default state of a nested group in the navigation sidebar.
 
 - `expanded: true`: Group is expanded by default.
 - `expanded: false` or omitted: Group is collapsed by default.
 
 <Note>
   The `expanded` property only affects nested groups--groups within groups. Top-level groups are always expanded and cannot be collapsed.
 </Note>
 
 ```json
@@ -119,6 +119,220 @@
 }
 ```
 
+### 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.
+
+<img
+  className="block dark:hidden pointer-events-none"
+  src="/images/navigation/tags-light.png"
+  alt="Navigation groups with tags displayed in the sidebar."
+/>
+
+<img
+  className="hidden dark:block pointer-events-none"
+  src="/images/navigation/tags-dark.png"
+  alt="Navigation groups with tags displayed in the sidebar."
+/>
+
+#### Adding tags to groups
+
+Add the `tag` field to any group object in your navigation configuration. The tag value is a string that appears next to the group name.
+
+```json
+{
+  "navigation": {
+    "groups": [
+      {
+        "group": "API v2",
+        "tag": "NEW",
+        "icon": "square-terminal",
+        "pages": ["api-v2/overview", "api-v2/authentication"]
+      },
+      {
+        "group": "Experimental features",
+        "tag": "BETA",
+        "icon": "flask",
+        "pages": ["experimental/feature-a", "experimental/feature-b"]
+      },
+      {
+        "group": "Legacy API",
+        "tag": "DEPRECATED",
+        "icon": "triangle-exclamation",
+        "pages": ["legacy/overview", "legacy/endpoints"]
+      }
+    ]
+  }
+}
+```
+
+#### Tag best practices
+
+Use tags strategically to guide users to the most relevant content:
+
+- **NEW**: Highlight recently added features, endpoints, or documentation sections
+- **BETA**: Indicate features in testing that may change or have limited support
+- **DEPRECATED**: Mark outdated content that will be removed in future versions
+- **UPDATED**: Draw attention to recently revised documentation
+- **PREVIEW**: Identify features available for early access or testing
+- **PRO** or **ENTERPRISE**: Denote premium or tier-specific features
+
+Keep tag text short and clear. Tags with more than 12 characters may be truncated in the sidebar.
+
+#### Tags with different navigation elements
+
+Tags work with groups, tabs, anchors, and other navigation elements. Use them consistently across your navigation structure.
+
+<CodeGroup>
+
+```json Groups with tags
+{
+  "navigation": {
+    "groups": [
+      {
+        "group": "Getting started",
+        "pages": ["quickstart", "installation"]
+      },
+      {
+        "group": "Advanced features",
+        "tag": "NEW",
+        "pages": ["webhooks", "custom-domains"]
+      },
+      {
+        "group": "Migration guides",
+        "tag": "UPDATED",
+        "pages": ["v1-to-v2", "breaking-changes"]
+      }
+    ]
+  }
+}
+```
+
+```json Tabs with nested tagged groups
+{
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "icon": "book-open",
+        "groups": [
+          {
+            "group": "Core concepts",
+            "pages": ["concepts/authentication", "concepts/rate-limits"]
+          },
+          {
+            "group": "Real-time features",
+            "tag": "BETA",
+            "icon": "bolt",
+            "pages": ["realtime/websockets", "realtime/streaming"]
+          }
+        ]
+      },
+      {
+        "tab": "API Reference",
+        "icon": "code",
+        "groups": [
+          {
+            "group": "REST API v3",
+            "tag": "NEW",
+            "pages": ["api/v3/users", "api/v3/projects"]
+          },
+          {
+            "group": "REST API v2",
+            "tag": "DEPRECATED",
+            "pages": ["api/v2/users", "api/v2/projects"]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+```json Anchors with tagged groups
+{
+  "navigation": {
+    "anchors": [
+      {
+        "anchor": "Documentation",
+        "icon": "book-open",
+        "groups": [
+          {
+            "group": "Getting started",
+            "pages": ["quickstart", "setup"]
+          },
+          {
+            "group": "AI integrations",
+            "tag": "PREVIEW",
+            "icon": "brain",
+            "pages": ["ai/overview", "ai/embeddings"]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+```json Products with tagged groups
+{
+  "navigation": {
+    "products": [
+      {
+        "product": "Platform",
+        "icon": "server",
+        "groups": [
+          {
+            "group": "Core features",
+            "pages": ["platform/overview", "platform/deployment"]
+          },
+          {
+            "group": "Edge functions",
+            "tag": "BETA",
+            "icon": "globe",
+            "pages": ["platform/edge/overview", "platform/edge/runtime"]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+</CodeGroup>
+
+#### Styling considerations
+
+Tags inherit your documentation's primary color scheme by default. The appearance adapts automatically to light and dark modes.
+
+Tags display inline with the group name and icon. When combined with icons, ensure your navigation remains scannable:
+
+```json
+{
+  "group": "Webhooks",
+  "tag": "NEW",
+  "icon": "webhook",
+  "pages": ["webhooks/setup", "webhooks/events"]
+}
+```
+
+For nested groups with tags, the tag appears at the appropriate nesting level:
+
+```json
+{
+  "group": "API Reference",
+  "pages": [
+    "api/overview",
+    {
+      "group": "Experimental endpoints",
+      "tag": "BETA",
+      "expanded": false,
+      "pages": ["api/experimental/search", "api/experimental/batch"]
+    }
+  ]
+}
+```
+
 ## 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.
@@ -296,7 +510,7 @@
 
 ## Dropdowns
 
 Dropdowns are contained in an expandable menu at the top of your sidebar navigation. Each item in a dropdown directs to a section of your documentation.
 
 <img
   className="block dark:hidden pointer-events-none"
@@ -411,7 +625,7 @@
 
 Integrate OpenAPI specifications directly into your navigation structure to automatically generate API documentation. Create dedicated API sections or place endpoint pages within other navigation components.
 
 Set a default OpenAPI specification at any level of your navigation hierarchy. Child elements will inherit this specification unless they define their own specification.
 
 <Note>
   When you add the `openapi` property to a navigation element (such as an anchor, tab, or group) without specifying any pages, Mintlify automatically generates pages for **all endpoints** defined in your OpenAPI specification.
@@ -581,7 +795,7 @@
 
 ## Nesting
 
 Navigation elements can be nested within each other to create complex hierarchies. You must have one root-level parent navigation element such as tabs, groups, or a dropdown. You can nest other types of navigation elements within your primary navigation pattern.
 
 Each navigation element can contain one type of child element at each level of your navigation hierarchy. For example, a tab can contain anchors that contain groups, but a tab cannot contain both anchors and groups at the same level.
 
@@ -805,7 +1019,7 @@
 
 ## Breadcrumbs
 
 Breadcrumbs display the full navigation path at the top of pages. Some themes have breadcrumbs enabled by default and others do not. You can control whether breadcrumbs are enabled for your site using the `styling` property in your `docs.json`.
 
 <CodeGroup>
 
@@ -829,10 +1043,10 @@
 
 ### Enable auto-navigation for groups
 
 When a user expands a navigation group, some themes will automatically navigate to the first page in the group. You can override a theme's default behavior using the `drilldown` option.
 
 - Set to `true` to force automatic navigation to the first page when a navigation group is selected.
 - Set to `false` to prevent navigation and only expand or collapse the group when it is selected.
 - Leave unset to use the theme's default behavior.
 
 <CodeGroup>