Improve directory listings documentation

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"]
 ---
 
@@ -118,68 +118,71 @@
 
 ### 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"
+            ]
+          }
         ]
       }
     ]
   }
 }
 ```
 
-```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.
 
 <Note>
-  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.
 </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
@@ -435,9 +438,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"
@@ -1006,9 +1009,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.
 
@@ -233,10 +233,9 @@
 
 #### `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"`
 
 ---
 
@@ -456,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
 
@@ -475,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"]
 ---
 
@@ -201,8 +201,8 @@
   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 name="navigation.directory" type='"none" | "accordion" | "card"'>
+  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).
 </ResponseField>
 
 ---