From 37324ef8def8e041cac8721251839bd3d5aaee59 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Thu, 9 Apr 2026 22:54:12 +0000
Subject: [PATCH 1/4] Improve directory listings docs with better examples and
clarity
Generated-By: mintlify-agent
---
organize/navigation.mdx | 67 +++++++++++++++++----------------
organize/settings-reference.mdx | 5 +--
organize/settings-structure.mdx | 4 +-
3 files changed, 39 insertions(+), 37 deletions(-)
diff --git a/organize/navigation.mdx b/organize/navigation.mdx
index 5a7b8b642..4950f4686 100644
--- a/organize/navigation.mdx
+++ b/organize/navigation.mdx
@@ -118,30 +118,46 @@ Use the `root` property to designate a main page for a group. When a group has a
### Directory listings
-When a group has a root page, you can generate a directory listing on that page. The directory listing displays the group's child pages and nested groups to give users an overview of the section's content.
+Use the `directory` property to automatically render a directory of child pages on group root pages. When you set `directory` on a navigation node, any group with a `root` page beneath that node displays a listing of its children below the page content.
-Set the `directory` property on a group, tab, or the top-level `navigation` object to enable directory listings. The property accepts three values:
+The `directory` property accepts three values:
-| Value | Description |
-|---------------|----------------------------------------------------|
-| `"accordion"` | Displays child pages in a list |
-| `"card"` | Displays child pages as horizontal cards |
-| `"none"` | Disables directory listings (default) |
+| Value | Behavior |
+| :---------- | :------- |
+| `"none"` | No directory listing. This is the default. |
+| `"accordion"` | Displays children in a collapsible list grouped by section. |
+| `"card"` | Displays children in a horizontal card layout. |
-The `directory` value inherits through the navigation hierarchy. If you set a `directory` value on a parent element, the value applies to all descendant groups unless overridden.
+The `directory` value inherits recursively through the navigation tree. Set it on a parent node and all descendant groups inherit the same value. Any descendant can override the inherited value, including setting `"none"` to opt out.
-```json Enable accordion directory for a group {6}
+You can set `directory` anywhere in the navigation object in your `docs.json` file, including on tabs, anchors, dropdowns, products, versions, languages, and individual groups.
+
+```json
{
"navigation": {
"groups": [
{
- "group": "API reference",
- "root": "api-overview",
+ "group": "Help Center",
+ "root": "help/index",
"directory": "accordion",
"pages": [
- "api-reference/authentication",
- "api-reference/endpoints",
- "api-reference/errors"
+ {
+ "group": "Getting Started",
+ "root": "help/getting-started/index",
+ "pages": [
+ "help/getting-started/quickstart",
+ "help/getting-started/install"
+ ]
+ },
+ {
+ "group": "API Reference",
+ "root": "help/api/index",
+ "directory": "none",
+ "pages": [
+ "help/api/overview",
+ "help/api/endpoints"
+ ]
+ }
]
}
]
@@ -149,26 +165,13 @@ The `directory` value inherits through the navigation hierarchy. If you set a `d
}
```
-```json Enable card directory for all groups {3}
-{
- "navigation": {
- "directory": "card",
- "groups": [
- {
- "group": "Guides",
- "root": "guides/overview",
- "pages": [
- "guides/quickstart",
- "guides/configuration"
- ]
- }
- ]
- }
-}
-```
+In this example:
+- **Help Center** uses `"accordion"` and its root page displays a directory listing.
+- **Getting Started** inherits `"accordion"` from its parent and also displays a directory listing.
+- **API Reference** overrides with `"none"`, so its root page does not display a directory listing.
- Directory listings only appear on group root pages. If a group does not have a `root` property, it cannot display a directory listing.
+ The `directory` property only affects groups that have a `root` page. Groups without a `root` page are not affected.
### Default expanded state
diff --git a/organize/settings-reference.mdx b/organize/settings-reference.mdx
index 6ea279187..f13febf15 100644
--- a/organize/settings-reference.mdx
+++ b/organize/settings-reference.mdx
@@ -233,10 +233,9 @@ Individual pages in your documentation.
#### `navigation.directory`
-Directory layout for group root pages. When set to `"accordion"` or `"card"`, groups with a `root` page display a directory listing of their child pages. Set to `"none"` to disable. Inherits recursively through the navigation hierarchy; descendants can override.
+Directory layout for root pages in navigation groups. Inherits recursively; descendants can override. See [Directory listings](/organize/navigation#directory-listings).
-**Type:** `"none"` | `"accordion"` | `"card"`
-**Default:** `"none"`
+**Type:** `"none"` | `"accordion"` | `"card"` — default `"none"`
---
diff --git a/organize/settings-structure.mdx b/organize/settings-structure.mdx
index b6098f688..699fdfec0 100644
--- a/organize/settings-structure.mdx
+++ b/organize/settings-structure.mdx
@@ -201,8 +201,8 @@ See [Navigation](/organize/navigation) for complete documentation on building yo
Individual [pages](/organize/navigation#pages) that make up your documentation.
-
- Directory layout for group root pages. Set to `"accordion"` or `"card"` to display a listing of child pages on group root pages. Set to `"none"` to disable. Inherits recursively; descendants can override. See [Directory listings](/organize/navigation#directory-listings) for more information.
+
+ Directory layout for root pages in navigation groups. When set, groups with a `root` page automatically display a listing of their children below the page content. Values inherit recursively through the navigation tree; descendants can override. See [Directory listings](/organize/navigation#directory-listings).
---
From ddea554e5e2116411ce283e5d991dcbf3a36cc8a Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Thu, 9 Apr 2026 15:57:48 -0700
Subject: [PATCH 2/4] Apply suggestion from @ethanpalm
---
organize/navigation.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/organize/navigation.mdx b/organize/navigation.mdx
index 4950f4686..28ed1ca52 100644
--- a/organize/navigation.mdx
+++ b/organize/navigation.mdx
@@ -118,7 +118,7 @@ Use the `root` property to designate a main page for a group. When a group has a
### Directory listings
-Use the `directory` property to automatically render a directory of child pages on group root pages. When you set `directory` on a navigation node, any group with a `root` page beneath that node displays a listing of its children below the page content.
+Use the `directory` property to automatically render a directory of child pages on group root pages. When you set `directory` on a navigation element, any group with a `root` page beneath that element displays a listing of its pages below the page content.
The `directory` property accepts three values:
From 8f7535355390d3b6f57ab35e74f425f9cd43f4bd Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Thu, 9 Apr 2026 15:58:54 -0700
Subject: [PATCH 3/4] Apply suggestions from code review
Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
---
organize/navigation.mdx | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/organize/navigation.mdx b/organize/navigation.mdx
index 28ed1ca52..69ddaab00 100644
--- a/organize/navigation.mdx
+++ b/organize/navigation.mdx
@@ -124,9 +124,9 @@ The `directory` property accepts three values:
| Value | Behavior |
| :---------- | :------- |
-| `"none"` | No directory listing. This is the default. |
-| `"accordion"` | Displays children in a collapsible list grouped by section. |
-| `"card"` | Displays children in a horizontal card layout. |
+| `"none"` | No directory listing. Default value. |
+| `"accordion"` | Displays child pages in a collapsible list grouped by section. |
+| `"card"` | Displays child pages in a horizontal card layout. |
The `directory` value inherits recursively through the navigation tree. Set it on a parent node and all descendant groups inherit the same value. Any descendant can override the inherited value, including setting `"none"` to opt out.
From 386fbd41503b7f2796c10c4ef343b5f0fa5deef8 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Thu, 9 Apr 2026 16:00:09 -0700
Subject: [PATCH 4/4] Apply suggestion from @ethanpalm
---
organize/navigation.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/organize/navigation.mdx b/organize/navigation.mdx
index 69ddaab00..8716a45f1 100644
--- a/organize/navigation.mdx
+++ b/organize/navigation.mdx
@@ -128,7 +128,7 @@ The `directory` property accepts three values:
| `"accordion"` | Displays child pages in a collapsible list grouped by section. |
| `"card"` | Displays child pages in a horizontal card layout. |
-The `directory` value inherits recursively through the navigation tree. Set it on a parent node and all descendant groups inherit the same value. Any descendant can override the inherited value, including setting `"none"` to opt out.
+The `directory` value inherits recursively through the navigation tree. Set it on a parent navigation element and all descendant groups inherit the same value. Any descendant can override the inherited value by setting `"directory": "none"`.
You can set `directory` anywhere in the navigation object in your `docs.json` file, including on tabs, anchors, dropdowns, products, versions, languages, and individual groups.