Add comprehensive tag documentation

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,293 @@
 }
 ```
 
+### Tags and labels
+
+Use tags to highlight the status or importance of navigation groups. Tags appear as small labels next to group names in the sidebar, helping users quickly identify new features, beta functionality, or deprecated content.
+
+<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."
+/>
+
+Add the `tag` property to any navigation group to display a label. Tags inherit your theme's primary color by default.
+
+```json
+{
+  "navigation": {
+    "groups": [
+      {
+        "group": "Getting started",
+        "tag": "NEW",
+        "pages": ["quickstart", "installation"]
+      },
+      {
+        "group": "Beta features",
+        "tag": "BETA",
+        "pages": ["feature-a", "feature-b"]
+      },
+      {
+        "group": "Legacy API",
+        "tag": "DEPRECATED",
+        "pages": ["v1/overview", "v1/endpoints"]
+      }
+    ]
+  }
+}
+```
+
+#### Common tag conventions
+
+Use consistent tag labels across your documentation to help users understand content status at a glance.
+
+<CardGroup cols={2}>
+  <Card title="NEW" icon="sparkles">
+    Recently added features or content
+  </Card>
+  <Card title="BETA" icon="flask">
+    Features in testing or early access
+  </Card>
+  <Card title="DEPRECATED" icon="triangle-exclamation">
+    Features scheduled for removal
+  </Card>
+  <Card title="PREVIEW" icon="eye">
+    Features available for preview
+  </Card>
+  <Card title="UPDATED" icon="arrow-rotate-right">
+    Recently updated content
+  </Card>
+  <Card title="PRO" icon="crown">
+    Premium or paid features
+  </Card>
+</CardGroup>
+
+#### Tags on different navigation elements
+
+Tags work with groups at any level of your navigation hierarchy, including nested groups, groups within tabs, and groups within anchors.
+
+<CodeGroup>
+
+```json Groups with tags
+{
+  "navigation": {
+    "groups": [
+      {
+        "group": "Core features",
+        "pages": ["overview"],
+        "tag": "STABLE"
+      },
+      {
+        "group": "Experimental",
+        "tag": "BETA",
+        "pages": [
+          "experiments/feature-flags",
+          {
+            "group": "Advanced experiments",
+            "tag": "ALPHA",
+            "pages": ["experiments/advanced/ml", "experiments/advanced/ai"]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+```json Tags in tabs
+{
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "groups": [
+          {
+            "group": "New features",
+            "tag": "NEW",
+            "pages": ["features/realtime", "features/webhooks"]
+          },
+          {
+            "group": "Legacy",
+            "tag": "DEPRECATED",
+            "pages": ["legacy/old-api"]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+```json Tags in anchors
+{
+  "navigation": {
+    "anchors": [
+      {
+        "anchor": "Documentation",
+        "icon": "book-open",
+        "groups": [
+          {
+            "group": "Beta program",
+            "tag": "BETA",
+            "pages": ["beta/overview", "beta/signup"]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+```json Tags in products
+{
+  "navigation": {
+    "products": [
+      {
+        "product": "Platform",
+        "icon": "server",
+        "groups": [
+          {
+            "group": "AI Features",
+            "tag": "NEW",
+            "pages": ["platform/ai/overview", "platform/ai/models"]
+          },
+          {
+            "group": "Classic API",
+            "tag": "DEPRECATED",
+            "pages": ["platform/classic/endpoints"]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+</CodeGroup>
+
+#### Best practices for tags
+
+<AccordionGroup>
+  <Accordion title="Keep tag text short">
+    Use 3-10 characters for optimal display. Long tags may be truncated on smaller screens.
+
+    **Good**: `NEW`, `BETA`, `PRO`
+
+    **Avoid**: `NEWLY RELEASED`, `EXPERIMENTAL FEATURE`
+  </Accordion>
+
+  <Accordion title="Use consistent terminology">
+    Establish a standard set of tags and use them consistently throughout your documentation. This helps users quickly understand what each tag means.
+
+    ```json
+    // Consistent approach
+    "tag": "BETA"      // Use everywhere for beta features
+    "tag": "NEW"       // Use everywhere for new features
+
+    // Inconsistent approach (avoid)
+    "tag": "BETA"      // Sometimes beta
+    "tag": "Preview"   // Sometimes preview
+    "tag": "Testing"   // Sometimes testing
+    ```
+  </Accordion>
+
+  <Accordion title="Remove tags when no longer relevant">
+    Update or remove tags as content matures. A feature marked "NEW" for months loses its impact.
+
+    ```json
+    // After a feature is stable, remove the tag
+    {
+      "group": "Webhooks",
+      // "tag": "NEW",  // Remove after 2-3 months
+      "pages": ["webhooks/setup", "webhooks/events"]
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Use tags sparingly">
+    Too many tags reduce their effectiveness. Reserve tags for truly important status indicators.
+
+    ```json
+    // Good: Strategic use of tags
+    {
+      "groups": [
+        {
+          "group": "Core API",
+          "pages": ["..."]
+        },
+        {
+          "group": "Realtime features",
+          "tag": "NEW",
+          "pages": ["..."]
+        },
+        {
+          "group": "Legacy endpoints",
+          "tag": "DEPRECATED",
+          "pages": ["..."]
+        }
+      ]
+    }
+
+    // Avoid: Overusing tags
+    {
+      "groups": [
+        {
+          "group": "Core API",
+          "tag": "STABLE",  // Unnecessary
+          "pages": ["..."]
+        },
+        {
+          "group": "Authentication",
+          "tag": "IMPORTANT",  // Unnecessary
+          "pages": ["..."]
+        },
+        {
+          "group": "Webhooks",
+          "tag": "POPULAR",  // Unnecessary
+          "pages": ["..."]
+        }
+      ]
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Consider your audience">
+    Choose tags that resonate with your users. Developer-focused docs might use "ALPHA" and "BETA", while business-focused docs might prefer "PREVIEW" and "COMING SOON".
+  </Accordion>
+</AccordionGroup>
+
+#### Styling considerations
+
+Tags automatically inherit your theme's primary color defined in the `colors` field of your `docs.json`. The tag appearance adapts to your chosen theme and color scheme.
+
+```json docs.json
+{
+  "theme": "mint",
+  "colors": {
+    "primary": "#3B82F6"  // Tags will use this color
+  },
+  "navigation": {
+    "groups": [
+      {
+        "group": "New features",
+        "tag": "NEW",  // Displays in primary color
+        "pages": ["..."]
+      }
+    ]
+  }
+}
+```
+
+<Note>
+  Tags cannot be individually styled with custom colors. They use your site's primary color to maintain visual consistency across your documentation.
+</Note>
+
 ## 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.
@@ -271,7 +558,7 @@
 Use global anchors for external links that should appear on all pages, regardless of which section of your navigation the user is viewing. Global anchors are particularly useful for linking to resources outside your documentation, such as a blog, community forum, or support portal.
 
 <Note>
   Global anchors must include an `href` field pointing to an external URL. They cannot contain relative paths.
 </Note>
 
 ```json
@@ -298,7 +585,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"
@@ -413,10 +700,10 @@
 
 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.
 
   To control which endpoints appear, explicitly list the desired endpoints in a `pages` array.
 </Note>
@@ -513,7 +800,7 @@
 
 In the `navigation` object, `languages` is an array where each entry is an object that requires a `language` field and can contain any other navigation fields.
 
 We currently support the following languages for localization:
 
 <CardGroup cols={2}>
   <Card title="Arabic (ar)" icon="/images/navigation/languages/ar.png" horizontal />
@@ -575,9 +862,9 @@
 
 ## 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.
 
 <CodeGroup>
 
@@ -799,7 +1086,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>
 
@@ -823,10 +1110,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>