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
 {
@@ -116,15 +116,82 @@
 }
 ```
 
+### Directory
+
+Use the `directory` property on a group to automatically render a listing of its child pages below the root page content. This is useful for help centers, knowledge bases, or any section where you want users to browse all available pages from a single entry point.
+
+The `directory` property accepts the following values:
+
+| Value | Behavior |
+|---|---|
+| `"none"` | Default. No directory listing is rendered. |
+| `"accordion"` | Renders child pages as a grouped, expandable list. |
+| `"card"` | Renders child pages as a horizontal card layout. |
+
+The `directory` value inherits recursively through nested groups. Set `directory` on a parent group and all nested groups inherit the same value unless they explicitly override it.
+
+<Note>
+  The `directory` property requires the group to have a `root` page. The directory listing appears on the root page, below its content.
+</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": "Billing",
+            "root": "help/billing/index",
+            "directory": "card",
+            "pages": [
+              "help/billing/plans",
+              "help/billing/invoices"
+            ]
+          },
+          {
+            "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** uses `"accordion"` (inherited from Help Center).
+- **Billing** uses `"card"` (overrides the inherited value).
+- **API Reference** uses `"none"` (opts out of directory listings).
+
 ### 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 +447,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 +1018,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.
 
@@ -223,7 +223,9 @@
 
 Groups for organizing content into labeled sections.
 
-**Type:** array of object
+**Type:** array of object—each with: `group` (string, required), `pages` (array, required), `root` (string), `directory` (`"none"` | `"accordion"` | `"card"`), `expanded` (boolean), `icon` (string), `iconType` (string), `tag` (string)
+
+The `directory` field renders a listing of child pages on the group's root page. Values inherit recursively through nested groups. Set to `"none"` to opt out. See [Directory](/organize/navigation#directory).
 
 #### `navigation.pages`
 
@@ -449,14 +451,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 +470,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"]
 ---
 
@@ -195,6 +195,28 @@
 
 <ResponseField name="navigation.groups" type="array of object">
   [Groups](/organize/navigation#groups) for organizing content into sections.
+
+  <Expandable title="navigation.groups">
+    <ResponseField name="group" type="string" required>
+      Display name of the group.
+    </ResponseField>
+    <ResponseField name="pages" type="array" required>
+      Pages and nested groups within this group.
+    </ResponseField>
+    <ResponseField name="root" type="string">
+      Path to the root page for this group. When set, clicking the group title navigates to this page. See [Root page](/organize/navigation#root-page).
+    </ResponseField>
+    <ResponseField name="directory" type='"none" | "accordion" | "card"'>
+      Renders a directory listing of child pages on the group's root page. Inherits recursively through nested groups. Set to `"none"` to opt out. See [Directory](/organize/navigation#directory).
+    </ResponseField>
+    <ResponseField name="expanded" type="boolean">
+      Whether a nested group is expanded by default. Only applies to groups nested inside other groups.
+    </ResponseField>
+    <IconsOptional />
+    <ResponseField name="tag" type="string">
+      Badge label displayed next to the group name.
+    </ResponseField>
+  </Expandable>
 </ResponseField>
 
 <ResponseField name="navigation.pages" type="array of string or object">