Add tags and labels documentation

organize/pages.mdx

@@ -73,6 +73,248 @@
 ---
 ```
 
+## Tags and labels
+
+Tags are visual indicators that appear next to page titles and navigation groups in your sidebar. Use tags to highlight the status or importance of content, such as new features, beta functionality, or deprecated endpoints.
+
+### Tag vs label
+
+Mintlify uses the term **tag** consistently across both page frontmatter and navigation configuration. There is no separate "label" concept—tags serve as the universal labeling mechanism throughout your documentation.
+
+- **Page-level tags**: Defined in page frontmatter using the `tag` property
+- **Group-level tags**: Defined in navigation groups using the `tag` property
+
+Both types of tags appear as small badges in the sidebar navigation, helping users quickly identify the status or category of content.
+
+### Where tags appear
+
+Tags display in the following locations:
+
+- **Sidebar navigation**: Next to page titles and group names
+- **Search results**: Tags from page frontmatter appear alongside search results
+- **Navigation hierarchy**: Tags inherit visual styling from your theme
+
+Tags do not appear in page content, browser tabs, or SEO meta tags—they are purely navigational indicators.
+
+### Using tags in page frontmatter
+
+Add a tag to any page by including the `tag` property in your frontmatter:
+
+```yaml
+---
+title: "Webhooks API"
+tag: "BETA"
+---
+```
+
+The tag appears next to the page title in the sidebar navigation. You can use any string value for tags, but keep them short (typically 3-8 characters) for optimal display.
+
+### Using tags in navigation groups
+
+Add tags to navigation groups in your `docs.json` to label entire sections:
+
+```json
+{
+  "navigation": {
+    "groups": [
+      {
+        "group": "Experimental features",
+        "tag": "BETA",
+        "pages": ["experimental/feature-a", "experimental/feature-b"]
+      }
+    ]
+  }
+}
+```
+
+Group tags appear next to the group name in the sidebar, indicating that all pages within the group share that status.
+
+### Common tag use cases
+
+Use tags to communicate content status and guide user expectations:
+
+<AccordionGroup>
+  <Accordion title="NEW - Recently added features">
+    Highlight new features, endpoints, or documentation sections that users should explore.
+
+    ```yaml
+    ---
+    title: "Real-time notifications"
+    tag: "NEW"
+    ---
+    ```
+  </Accordion>
+
+  <Accordion title="BETA - Pre-release functionality">
+    Mark features that are available but still under active development or testing.
+
+    ```yaml
+    ---
+    title: "GraphQL API"
+    tag: "BETA"
+    ---
+    ```
+  </Accordion>
+
+  <Accordion title="DEPRECATED - Legacy content">
+    Warn users about features or endpoints that will be removed in future versions.
+
+    ```yaml
+    ---
+    title: "Legacy authentication"
+    tag: "DEPRECATED"
+    ---
+    ```
+  </Accordion>
+
+  <Accordion title="PREVIEW - Early access features">
+    Indicate features available to select users or requiring special access.
+
+    ```yaml
+    ---
+    title: "AI-powered search"
+    tag: "PREVIEW"
+    ---
+    ```
+  </Accordion>
+
+  <Accordion title="ENTERPRISE - Paid tier features">
+    Distinguish features available only to enterprise or premium customers.
+
+    ```yaml
+    ---
+    title: "Advanced analytics"
+    tag: "ENTERPRISE"
+    ---
+    ```
+  </Accordion>
+</AccordionGroup>
+
+### Custom metadata properties
+
+Beyond standard frontmatter fields, you can add custom metadata properties to organize and categorize your documentation:
+
+```yaml
+---
+title: "User authentication"
+description: "Learn how to authenticate users"
+product: "API"
+version: "2.0"
+audience: "developers"
+difficulty: "intermediate"
+---
+```
+
+Custom metadata properties:
+
+- **Are valid YAML**: Any valid YAML key-value pair works
+- **Do not appear in the UI**: Custom properties are not displayed to users by default
+- **Cannot be queried or filtered**: Mintlify does not provide built-in search or filtering for custom metadata
+- **Serve as documentation**: Use them to organize content internally or for future tooling
+
+Custom metadata is useful for internal organization, documentation workflows, or integration with external tools that process your MDX files.
+
+### Page-level vs global metadata
+
+Understanding when to use page frontmatter versus global configuration in `docs.json` helps you maintain consistent, scalable documentation.
+
+#### Page-level metadata (frontmatter)
+
+Use frontmatter for properties that vary between individual pages:
+
+```yaml
+---
+title: "Getting started with webhooks"
+description: "Set up webhook endpoints to receive real-time events"
+icon: "webhook"
+tag: "NEW"
+---
+```
+
+**Best for:**
+- Page-specific titles, descriptions, and icons
+- Individual page tags and status indicators
+- Page-specific SEO metadata
+- Custom metadata unique to each page
+- Page layout modes (wide, custom, frame)
+
+#### Global metadata (docs.json)
+
+Use `docs.json` for properties that apply across multiple pages or define site-wide behavior:
+
+```json
+{
+  "name": "Acme API Documentation",
+  "logo": "/logo.png",
+  "metadata": {
+    "og:image": "/social-preview.jpg",
+    "twitter:site": "@acmeapi"
+  },
+  "navigation": {
+    "groups": [
+      {
+        "group": "API Reference",
+        "tag": "STABLE",
+        "pages": ["api/users", "api/orders"]
+      }
+    ]
+  }
+}
+```
+
+**Best for:**
+- Site-wide branding (name, logo, favicon)
+- Default SEO metadata for all pages
+- Navigation structure and hierarchy
+- Group-level tags that apply to multiple pages
+- Theme and styling configuration
+- Global features (analytics, search, feedback)
+
+#### When to use each
+
+| Scenario | Use frontmatter | Use docs.json |
+|----------|----------------|---------------|
+| Set a page title | ✓ | |
+| Add a tag to one page | ✓ | |
+| Add a tag to a group of pages | | ✓ |
+| Configure site-wide SEO | | ✓ |
+| Override SEO for one page | ✓ | |
+| Organize navigation structure | | ✓ |
+| Set page-specific icon | ✓ | |
+| Set group-level icon | | ✓ |
+
+**Example: Combining both approaches**
+
+```yaml Page frontmatter (api/webhooks.mdx)
+---
+title: "Webhooks"
+description: "Receive real-time event notifications"
+tag: "BETA"
+icon: "webhook"
+---
+```
+
+```json Global configuration (docs.json)
+{
+  "navigation": {
+    "groups": [
+      {
+        "group": "API Reference",
+        "tag": "STABLE",
+        "icon": "square-terminal",
+        "pages": [
+          "api/authentication",
+          "api/users",
+          "api/webhooks"
+        ]
+      }
+    ]
+  }
+}
+```
+
+In this example, the "Webhooks" page displays both its page-level tag ("BETA") and inherits the group structure from `docs.json`. The page-level tag takes precedence for that specific page, while other pages in the group would display the group-level tag if they don't have their own.
+
 ## Page mode
 
 Control your page's layout with the `mode` setting.
@@ -115,7 +357,7 @@
 
 ### Frame
 
 Frame mode provides a layout similar to custom mode but keeps the sidebar navigation. Use this mode to include custom HTML and components while preserving the default navigation experience. Only Aspen, Almond, and Luma themes support frame mode.
 
 ```yaml
 ---