Document directory listings for navigation groups

organize/navigation.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Navigation"
 description: "Configure your documentation site navigation with groups, pages, dropdowns, tabs, and anchors in docs.json to build a sidebar structure."
 keywords: ["navigation structure", "sidebar configuration", "page organization", "navigation groups"]
 ---
 
@@ -58,7 +58,7 @@
   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
 {
@@ -116,15 +116,83 @@
 }
 ```
 
+### Directory listings
+
+Use the `directory` property to automatically display a directory of child pages below the content of a group's root page. This is useful for hub pages or landing pages that serve as entry points to a section.
+
+Set `directory` on any navigation node—including the top-level `navigation` object, groups, tabs, anchors, dropdowns, products, versions, or languages. The value inherits recursively through descendant nodes, so you can set it once at a high level and override it deeper in the tree.
+
+| Value | Behavior |
+|---|---|
+| `"none"` | Default. No directory UI is rendered. |
+| `"accordion"` | Displays child pages in a grouped, collapsible list below the root page content. |
+| `"card"` | Displays child pages as horizontal cards below the root page content. |
+
+<Note>
+  The `directory` property only affects groups that have a `root` page. Groups without a root page are not affected.
+</Note>
+
+```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/overview", "help/api/endpoints"]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+In this example:
+- **Help Center** uses `"accordion"` (set explicitly).
+- **Getting Started** inherits `"accordion"` from its parent.
+- **API Reference** overrides with `"none"`, so its root page does not show a directory.
+
+You can also set `directory` at the top level of the `navigation` object to apply a default across your entire site:
+
+```json
+{
+  "navigation": {
+    "directory": "card",
+    "groups": [
+      {
+        "group": "Guides",
+        "root": "guides/index",
+        "pages": ["guides/quickstart", "guides/deployment"]
+      }
+    ]
+  }
+}
+```
+
 ### Default expanded state
 
 Use the `expanded` property to control the default state of a nested group in the navigation sidebar.
 
 - `expanded: true`: Group is expanded by default.
 - `expanded: false` or omitted: Group is collapsed by default.
 
 <Note>
   The `expanded` property only affects nested groups--groups within groups. Top-level groups are always expanded and cannot be collapsed.
 </Note>
 
 ```json
@@ -380,9 +448,9 @@
 }
 ```
 
 ## Dropdowns
 
 Dropdowns are an expandable menu at the top of your sidebar navigation. Each item in a dropdown directs to a section of your documentation.
 
 <img
   className="block dark:hidden pointer-events-none"
@@ -951,9 +1019,9 @@
 
 </CodeGroup>
 
 ## Breadcrumbs
 
 Breadcrumbs display the full navigation path at the top of pages. Some themes have breadcrumbs enabled by default and others do not. You can control whether breadcrumbs display on your site using the `styling` property in your `docs.json`.
 
 <CodeGroup>
 

organize/settings-reference.mdx

@@ -1,6 +1,6 @@
 ---
 title: "docs.json schema reference"
 description: "Complete reference for every docs.json configuration property with types, default values, descriptions, and usage examples for your docs site."
 keywords: ["docs.json", "schema", "reference", "configuration", "all settings", "properties", "complete"]
 ---
 
@@ -41,6 +41,7 @@
 | `footer.links` | array | No | None |
 | `banner.content` | string | No | None |
 | `banner.dismissible` | boolean | No | `false` |
+| `navigation.directory` | `"none"` \| `"accordion"` \| `"card"` | No | `"none"` |
 | `interaction.drilldown` | boolean | No | Theme default |
 | `contextual.options` | array | No | None |
 | `contextual.display` | `"header"` \| `"toc"` | No | `"header"` |
@@ -157,7 +158,7 @@
 
 ##### `navigation.global.dropdowns`
 
 Dropdown menus.
 
 **Type:** array of object—each with: `dropdown` (string, required), `icon` (string), `iconType` (string), `hidden` (boolean), `href` (string uri, required)
 
@@ -209,7 +210,7 @@
 
 #### `navigation.dropdowns`
 
 Dropdown menus.
 
 **Type:** array of object—see `navigation.global.dropdowns` for shape.
 
@@ -219,6 +220,13 @@
 
 **Type:** array of object—see `navigation.global.products` for shape.
 
+#### `navigation.directory`
+
+Default directory listing style for group root pages. Inherits recursively through descendant navigation nodes. Descendants can override with their own `directory` value. See [Directory listings](/organize/navigation#directory-listings).
+
+**Type:** `"none"` | `"accordion"` | `"card"`
+**Default:** `"none"`
+
 #### `navigation.groups`
 
 Groups for organizing content into labeled sections.
@@ -449,14 +457,14 @@
 
 Code block theme configuration.
 
 **Type:** `"system"` | `"dark"` | string (Shiki theme name) | object
 **Default:** `"system"`
 
 When an object:
 
 ##### `styling.codeblocks.theme`
 
 A single Shiki theme name for both modes, or an object with `light` and `dark` Shiki theme names.
 
 **Type:** string or object
 
@@ -468,7 +476,7 @@
 
 ###### `styling.codeblocks.languages.custom`
 
 Paths to JSON files describing custom Shiki languages in [TextMate grammar format](https://macromates.com/manual/en/language_grammars).
 
 **Type:** array of string
 

organize/settings-structure.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Site structure"
 description: "Configure navbar, navigation groups, footer links, banner, contextual menu, redirects, and other structural elements in your docs.json file."
 keywords: ["navbar", "navigation", "footer", "banner", "contextual", "redirects", "variables", "metadata", "docs.json"]
 ---
 
@@ -193,6 +193,10 @@
   Product switcher for sites with multiple [products](/organize/navigation#products).
 </ResponseField>
 
+<ResponseField name="navigation.directory" type='"none" | "accordion" | "card"'>
+  Default [directory listing](/organize/navigation#directory-listings) style for group root pages. When set, all descendant navigation nodes inherit this value unless they specify their own `directory`. Defaults to `"none"`.
+</ResponseField>
+
 <ResponseField name="navigation.groups" type="array of object">
   [Groups](/organize/navigation#groups) for organizing content into sections.
 </ResponseField>