Document directory listings for navigation group root pages

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"]
 ---
 
@@ -116,15 +116,70 @@
 }
 ```
 
+### 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.
+
+Set the `directory` property on a group, tab, or the top-level `navigation` object to enable directory listings. The 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)              |
+
+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.
+
+```json Enable accordion directory for a group {6}
+{
+  "navigation": {
+    "groups": [
+      {
+        "group": "API reference",
+        "root": "api-overview",
+        "directory": "accordion",
+        "pages": [
+          "api-reference/authentication",
+          "api-reference/endpoints",
+          "api-reference/errors"
+        ]
+      }
+    ]
+  }
+}
+```
+
+```json Enable card directory for all groups {3}
+{
+  "navigation": {
+    "directory": "card",
+    "groups": [
+      {
+        "group": "Guides",
+        "root": "guides/overview",
+        "pages": [
+          "guides/quickstart",
+          "guides/configuration"
+        ]
+      }
+    ]
+  }
+}
+```
+
+<Note>
+  Directory listings only appear on group root pages. If a group does not have a `root` property, it cannot display a directory listing.
+</Note>
+
 ### 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 +435,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 +1006,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"]
 ---
 
@@ -157,7 +157,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 +209,7 @@
 
 #### `navigation.dropdowns`
 
 Dropdown menus.
 
 **Type:** array of object—see `navigation.global.dropdowns` for shape.
 
@@ -231,6 +231,13 @@
 
 **Type:** array of string or object
 
+#### `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.
+
+**Type:** `"none"` | `"accordion"` | `"card"`
+**Default:** `"none"`
+
 ---
 
 ### `description`
@@ -449,14 +456,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 +475,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"]
 ---
 
@@ -201,6 +201,10 @@
   Individual [pages](/organize/navigation#pages) that make up your documentation.
 </ResponseField>
 
+<ResponseField name="navigation.directory" type="string" default="none">
+  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.
+</ResponseField>
+
 ---
 
 ### `navbar`