Add comprehensive guide on hiding UI elements

customize/hiding-ui-elements.mdx

@@ -0,0 +1,343 @@
+---
+title: "Hiding UI elements"
+description: "Control the visibility of navigation elements, API sections, and other UI components in your documentation."
+keywords: ["hide navigation", "hide sidebar", "hide tabs", "hide API sections", "UI visibility", "custom CSS"]
+---
+
+Control which UI elements appear in your documentation by hiding navigation items, API sections, and other components. This guide covers all methods for managing UI visibility.
+
+## Hiding navigation elements
+
+### Hide pages
+
+Hide individual pages from navigation while keeping them accessible via direct URL. Hidden pages are useful for content you want to reference or link to, but don't want listed in your navigation.
+
+<Note>
+  Hidden pages are automatically excluded from search engines, sitemaps, and AI context. See [Hidden pages](/organize/hidden-pages) for complete details.
+</Note>
+
+**Method 1: Set `hidden: true` in frontmatter**
+
+Add `hidden: true` to a page's frontmatter to remove it from navigation while keeping it in your `docs.json`:
+
+```yaml
+---
+title: "My hidden page"
+hidden: true
+---
+```
+
+**Method 2: Remove from navigation**
+
+Simply don't include the page in your `docs.json` navigation structure. The page file can remain in your repository but won't appear in navigation.
+
+### Hide groups
+
+Hide entire groups of pages by setting the `hidden` property in your `docs.json`:
+
+```json
+{
+  "navigation": {
+    "groups": [
+      {
+        "group": "Getting started",
+        "hidden": true,
+        "pages": ["index", "quickstart"]
+      },
+      {
+        "group": "Guides",
+        "pages": ["guides/guide-1", "guides/guide-2"]
+      }
+    ]
+  }
+}
+```
+
+In this example, the "Getting started" group is hidden while "Guides" remains visible.
+
+### Hide tabs
+
+Hide tabs from your navigation by adding the `hidden` property:
+
+```json
+{
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Home",
+        "hidden": true,
+        "pages": ["index", "quickstart"]
+      },
+      {
+        "tab": "API Reference",
+        "pages": ["api/overview"]
+      }
+    ]
+  }
+}
+```
+
+### Hide anchors and dropdowns
+
+The `hidden` property works consistently across all navigation elements:
+
+```json
+{
+  "navigation": {
+    "anchors": [
+      {
+        "anchor": "Documentation",
+        "icon": "book-open",
+        "hidden": true,
+        "pages": ["quickstart", "development"]
+      }
+    ],
+    "dropdowns": [
+      {
+        "dropdown": "Internal docs",
+        "icon": "lock",
+        "hidden": true,
+        "pages": ["internal/page-1"]
+      }
+    ]
+  }
+}
+```
+
+## Hiding API documentation sections
+
+### Hide specific API endpoints
+
+For OpenAPI-generated documentation, control which endpoints appear using the `x-hidden` and `x-excluded` extensions in your OpenAPI specification.
+
+**`x-hidden`: Create page but hide from navigation**
+
+The endpoint page exists and is accessible via direct URL, but doesn't appear in navigation:
+
+```json
+{
+  "paths": {
+    "/internal_endpoint": {
+      "get": {
+        "x-hidden": true,
+        "description": "Internal endpoint accessible by URL only",
+        "responses": { }
+      }
+    }
+  }
+}
+```
+
+**`x-excluded`: Completely exclude from documentation**
+
+The endpoint is not documented at all:
+
+```json
+{
+  "paths": {
+    "/secret_endpoint": {
+      "get": {
+        "x-excluded": true,
+        "description": "This endpoint will not be published",
+        "responses": { }
+      }
+    }
+  }
+}
+```
+
+Common use cases:
+- **`x-hidden`**: Beta features, internal-only endpoints you want to document, endpoints for specific users
+- **`x-excluded`**: Deprecated endpoints, truly internal APIs, endpoints not ready for documentation
+
+See [Manage page visibility](/api-playground/managing-page-visibility) for complete details.
+
+### Control which endpoints are generated
+
+When using OpenAPI specifications, explicitly list which endpoints to include in your navigation:
+
+```json
+{
+  "navigation": {
+    "groups": [
+      {
+        "group": "API reference",
+        "openapi": "/path/to/openapi.json",
+        "pages": [
+          "overview",
+          "authentication",
+          "GET /users",
+          "POST /users"
+        ]
+      }
+    ]
+  }
+}
+```
+
+Without a `pages` array, Mintlify automatically generates pages for all endpoints in your specification.
+
+## Hiding UI components with custom CSS
+
+Use custom CSS to hide specific UI elements across your documentation. Create a `style.css` file in your repository to apply custom styles.
+
+### Hide the sidebar on specific pages
+
+```css
+/* Hide sidebar on homepage */
+body[data-path="/"] #sidebar {
+  display: none;
+}
+
+/* Expand content area when sidebar is hidden */
+body[data-path="/"] #content-area {
+  max-width: 100%;
+  margin: 0 auto;
+}
+```
+
+### Hide the table of contents
+
+```css
+#table-of-contents {
+  display: none;
+}
+```
+
+### Hide navigation elements
+
+```css
+/* Hide the navbar */
+#navbar {
+  display: none;
+}
+
+/* Hide specific navigation items */
+.nav-anchor[data-anchor="Internal"] {
+  display: none;
+}
+
+/* Hide the footer */
+footer {
+  display: none;
+}
+```
+
+### Common UI element selectors
+
+Mintlify provides identifiers and selectors for common UI elements:
+
+<AccordionGroup>
+  <Accordion title="Navigation identifiers">
+    - `#navbar` - Top navigation bar
+    - `#sidebar` - Left sidebar navigation
+    - `#sidebar-content` - Sidebar content area
+    - `#table-of-contents` - Right table of contents
+    - `#navigation-items` - Navigation menu items
+    - `.nav-anchor` - Anchor navigation items
+    - `.nav-tabs` - Tab navigation bar
+    - `.nav-tabs-item` - Individual tab items
+    - `.nav-dropdown-trigger` - Dropdown menu triggers
+  </Accordion>
+  <Accordion title="Content identifiers">
+    - `#header` - Page header
+    - `#footer` - Page footer
+    - `#content-area` - Main content area
+    - `#body-content` - Page body content
+    - `#page-title` - Page title element
+    - `.eyebrow` - Breadcrumb/section eyebrow
+    - `#pagination` - Page navigation (prev/next)
+  </Accordion>
+  <Accordion title="API playground identifiers">
+    - `.api-section` - API documentation sections
+    - `.api-section-heading` - API section headings
+    - `.api-playground-input` - API playground input fields
+    - `.request-example` - Request example sections
+    - `.response-example` - Response example sections
+    - `.tryit-button` - "Try it" buttons
+  </Accordion>
+</AccordionGroup>
+
+<Tip>
+  Use your browser's inspect element tool to find specific selectors for elements you want to hide.
+</Tip>
+
+<Warning>
+  Element selectors may change as the platform evolves. Test your custom CSS after platform updates.
+</Warning>
+
+### Example: Hide sidebar on landing page
+
+Create a `style.css` file in your repository:
+
+```css
+/* Hide sidebar and expand content on homepage */
+body[data-path="/"] #sidebar,
+body[data-path="/"] #table-of-contents {
+  display: none;
+}
+
+body[data-path="/"] #content-container {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 2rem;
+}
+```
+
+## Hiding the Mintlify badge
+
+The "Powered by Mintlify" badge appears in the footer on free plans. This badge is automatically removed on paid plans (Pro and Enterprise).
+
+To remove the badge:
+1. Upgrade to a Pro or Enterprise plan
+2. The badge will be automatically hidden from your documentation
+
+<Note>
+  The badge cannot be hidden on free plans through CSS or configuration. It is a platform feature that distinguishes paid plans.
+</Note>
+
+## Controlling visibility by user group
+
+For authenticated documentation, show or hide content based on user groups using frontmatter:
+
+```yaml
+---
+title: "Enterprise features"
+groups: ["enterprise", "admin"]
+---
+```
+
+This requires [authentication setup](/deploy/authentication-setup) with group-based access control.
+
+## Best practices
+
+<AccordionGroup>
+  <Accordion title="When to hide vs. exclude">
+    - **Hide** (`hidden: true` or `x-hidden`): Content exists and is accessible via URL, useful for linking or direct access
+    - **Exclude** (remove from navigation or `x-excluded`): Content should not be accessible at all
+  </Accordion>
+  <Accordion title="SEO considerations">
+    - Hidden pages are automatically excluded from search engines and sitemaps
+    - Use `noindex: true` in frontmatter to exclude from search engines while keeping in navigation
+    - Hidden pages are not included in AI assistant context by default
+  </Accordion>
+  <Accordion title="Navigation organization">
+    - Hide deprecated content rather than deleting it to maintain URL stability
+    - Use hidden pages for beta features before public launch
+    - Hide internal documentation sections while keeping them accessible to your team
+  </Accordion>
+  <Accordion title="Custom CSS caution">
+    - Test custom CSS across different themes and screen sizes
+    - Avoid hiding critical navigation elements that users need
+    - Document your custom CSS for future maintenance
+    - Be aware that platform updates may affect custom selectors
+  </Accordion>
+</AccordionGroup>
+
+## Related resources
+
+- [Hidden pages](/organize/hidden-pages) - Complete guide to hiding pages from navigation
+- [Navigation](/organize/navigation) - Configure your documentation structure
+- [Custom scripts](/customize/custom-scripts) - Add custom CSS and JavaScript
+- [Manage page visibility](/api-playground/managing-page-visibility) - Control API endpoint visibility
+- [Authentication setup](/deploy/authentication-setup) - Set up group-based access control

docs.json

@@ -51,7 +51,8 @@
                   "customize/fonts",
                   "customize/custom-scripts",
                   "customize/react-components",
-                  "customize/custom-404-page"
+                  "customize/custom-404-page",
+                  "customize/hiding-ui-elements"
                 ]
               },
               {