diff --git a/changelog.mdx b/changelog.mdx
index 20c3cfba0..ae1894a00 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -5,6 +5,14 @@ rss: true
noindex: true
---
+
+
+ ## Directory listings for group root pages
+
+ Navigation groups with a [root page](/organize/navigation#root-page) can now display an automatic directory of their child pages. Set the new [`directory`](/organize/navigation#directory-listings) property on any navigation node to `"accordion"` or `"card"` to render a listing below the root page content. The value inherits recursively, so you can set it once at a high level and override it on individual groups with `"none"`.
+
+
+
## get_page MCP tool
diff --git a/organize/navigation.mdx b/organize/navigation.mdx
index 421b8a9ab..3106fb880 100644
--- a/organize/navigation.mdx
+++ b/organize/navigation.mdx
@@ -58,7 +58,7 @@ Use groups to organize your sidebar navigation into sections. You can nest group
alt="Decorative graphic of groups."
/>
-In the `navigation` object, `groups` is an array where each entry is an object that requires a `group` field and a `pages` field. The `icon`, `tag`, `root`, and `expanded` fields are optional.
+In the `navigation` object, `groups` is an array where each entry is an object that requires a `group` field and a `pages` field. The `icon`, `tag`, `root`, `expanded`, and `directory` fields are optional.
```json
{
@@ -141,6 +141,86 @@ Use the `expanded` property to control the default state of a nested group in th
}
```
+### Directory listings
+
+Use the `directory` property to automatically render a listing of child pages below the content on a group's [root page](#root-page). This is useful for hub or index pages that serve as entry points to a section.
+
+The `directory` property accepts one of these values:
+
+| Value | Behavior |
+|---|---|
+| `"accordion"` | Renders child pages in a grouped, collapsible list. |
+| `"card"` | Renders child pages as horizontal cards. |
+| `"none"` | No directory listing. This is the default. |
+
+
+ The `directory` property requires the group to have a `root` page. The directory listing renders on the root page, below its content.
+
+
+```json
+{
+ "navigation": {
+ "groups": [
+ {
+ "group": "Help Center",
+ "root": "help/index",
+ "directory": "accordion",
+ "pages": [
+ "help/getting-started",
+ "help/faq",
+ {
+ "group": "API Reference",
+ "root": "help/api/index",
+ "pages": [
+ "help/api/authentication",
+ "help/api/endpoints"
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+#### Inheritance
+
+The `directory` value inherits recursively. When you set `directory` on a parent node, all descendant groups with root pages inherit the same layout. Any descendant can override the inherited value.
+
+You can set `directory` on any navigation node, including the root `navigation` object, tabs, anchors, dropdowns, products, versions, and languages.
+
+```json
+{
+ "navigation": {
+ "groups": [
+ {
+ "group": "Help Center",
+ "root": "help/index",
+ "directory": "accordion",
+ "pages": [
+ {
+ "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/auth", "help/api/endpoints"]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+In this example:
+- **Help Center** uses `accordion` (set explicitly).
+- **Getting Started** inherits `accordion` from Help Center.
+- **API Reference** overrides with `none`, disabling the directory listing.
+
## 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.
diff --git a/organize/settings-reference.mdx b/organize/settings-reference.mdx
index 4671d91a9..c6ba5477b 100644
--- a/organize/settings-reference.mdx
+++ b/organize/settings-reference.mdx
@@ -219,9 +219,17 @@ Product switcher.
**Type:** array of object—see `navigation.global.products` for shape.
+#### `navigation.directory`
+
+Default [directory listing layout](/organize/navigation#directory-listings) for group root pages. Inherits recursively through the navigation tree; any descendant node can override.
+
+**Type:** `"none"` | `"accordion"` | `"card"`
+
+**Default:** `"none"`
+
#### `navigation.groups`
-Groups for organizing content into labeled sections.
+Groups for organizing content into labeled sections. Each group object supports `group` (string, required), `pages` (array, required), `icon` (string), `tag` (string), `root` (string), `expanded` (boolean), and `directory` (`"none"` | `"accordion"` | `"card"`).
**Type:** array of object
diff --git a/organize/settings-structure.mdx b/organize/settings-structure.mdx
index 9a90d9703..e5576be32 100644
--- a/organize/settings-structure.mdx
+++ b/organize/settings-structure.mdx
@@ -193,8 +193,36 @@ See [Navigation](/organize/navigation) for complete documentation on building yo
Product switcher for sites with multiple [products](/organize/navigation#products).
+
+ Default [directory listing layout](/organize/navigation#directory-listings) for group root pages under this navigation node. Inherits recursively; any descendant can override. Defaults to `"none"`.
+
+
[Groups](/organize/navigation#groups) for organizing content into sections.
+
+
+
+ Display name for the group.
+
+
+ Pages and nested groups within this group.
+
+
+ Path to the group's [root page](/organize/navigation#root-page). Clicking the group title navigates to this page.
+
+
+ Icon displayed next to the group name.
+
+
+ Badge label displayed next to the group name.
+
+
+ Whether a nested group is expanded by default.
+
+
+ [Directory listing layout](/organize/navigation#directory-listings) for the group's root page. Inherits from the parent navigation node if not set.
+
+