Document directory listing 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
 {
@@ -120,11 +120,11 @@
 
 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
@@ -141,6 +141,84 @@
 }
 ```
 
+### Directory listing
+
+Use the `directory` property to automatically display a listing of child pages on a group's [root page](#root-page). When a visitor opens the root page, a directory of the group's children renders below the page content.
+
+The `directory` property accepts three values:
+
+| Value | Behavior |
+|---|---|
+| `"none"` | Default. No directory is shown. |
+| `"accordion"` | Collapsible list-style directory grouped by section. |
+| `"card"` | Horizontal card layout. |
+
+<Note>
+  The `directory` property requires the group to have a `root` page. Only root pages render the directory listing.
+</Note>
+
+```json
+{
+  "navigation": {
+    "groups": [
+      {
+        "group": "Help Center",
+        "root": "help/overview",
+        "directory": "accordion",
+        "pages": [
+          {
+            "group": "Getting Started",
+            "root": "help/getting-started/overview",
+            "pages": [
+              "help/getting-started/quickstart",
+              "help/getting-started/install"
+            ]
+          },
+          {
+            "group": "Billing",
+            "root": "help/billing/overview",
+            "directory": "card",
+            "pages": [
+              "help/billing/plans",
+              "help/billing/invoices"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### Inheritance
+
+The `directory` value inherits recursively through the navigation tree. Child groups inherit the value from their parent unless they specify their own. Set `directory` to `"none"` on a child group to opt out of an inherited directory style.
+
+You can also set `directory` at the top level of the `navigation` object to apply a default style across your entire site.
+
+```json
+{
+  "navigation": {
+    "directory": "accordion",
+    "groups": [
+      {
+        "group": "Guides",
+        "root": "guides/overview",
+        "pages": ["guides/quickstart", "guides/deployment"]
+      },
+      {
+        "group": "API Reference",
+        "root": "api/overview",
+        "directory": "none",
+        "pages": ["api/authentication", "api/endpoints"]
+      }
+    ]
+  }
+}
+```
+
+In this example, the **Guides** group inherits the `"accordion"` style from the top-level `navigation`, while the **API Reference** group overrides it with `"none"`.
+
 ## 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.
@@ -380,9 +458,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 +1029,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.
 
@@ -225,6 +225,12 @@
 
 **Type:** array of object
 
+#### `navigation.directory`
+
+Directory listing style for group root pages. Inherits recursively through the navigation tree.
+
+**Type:** `"none"` | `"accordion"` | `"card"` — default `"none"`
+
 #### `navigation.pages`
 
 Individual pages in your documentation.
@@ -449,14 +455,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 +474,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"]
 ---
 
@@ -197,6 +197,10 @@
   [Groups](/organize/navigation#groups) for organizing content into sections.
 </ResponseField>
 
+<ResponseField name="navigation.directory" type='"none" | "accordion" | "card"'>
+  [Directory listing](/organize/navigation#directory-listing) style for group root pages. Inherits recursively through the navigation tree. Defaults to `"none"`.
+</ResponseField>
+
 <ResponseField name="navigation.pages" type="array of string or object">
   Individual [pages](/organize/navigation#pages) that make up your documentation.
 </ResponseField>