diff --git a/organize/navigation.mdx b/organize/navigation.mdx
index 5a7b8b642..8716a45f1 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 element, any group with a `root` page beneath that element displays a listing of its pages 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. 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 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 navigation element and all descendant groups inherit the same value. Any descendant can override the inherited value by setting `"directory": "none"`.
-```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).
---