diff --git a/organize/navigation.mdx b/organize/navigation.mdx index 421b8a9ab..3b273fba1 100644 --- a/organize/navigation.mdx +++ b/organize/navigation.mdx @@ -141,6 +141,61 @@ Use the `expanded` property to control the default state of a nested group in th } ``` +### Directory listings + +Use the `directory` property to automatically render a listing of child pages below the content of a group's [root page](#root-page). Directory listings help users discover and navigate to pages within a section without manually maintaining links on the root page. + +The `directory` property accepts three values: + +| Value | Behavior | +| --- | --- | +| `"none"` | Default. No directory listing is rendered. | +| `"accordion"` | Renders a collapsible, list-style directory organized by subgroups. | +| `"card"` | Renders a horizontal card layout of child pages. | + + + The `directory` property requires a [`root`](#root-page) page on the group. The directory listing appears on the root page below its content. + + +```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 the `accordion` directory style on its root page. +- **Getting Started** inherits the `accordion` style from its parent. +- **API Reference** overrides with `"none"` to opt out of the directory listing. + +#### Inheritance + +The `directory` value inherits down through the navigation tree. Set `directory` on a parent group and all nested groups with root pages inherit the same style. Override any nested group by setting its own `directory` value. Setting `"none"` on a group also applies to all of its children unless they override it. + ## 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. diff --git a/organize/settings-reference.mdx b/organize/settings-reference.mdx index 4671d91a9..db94993a6 100644 --- a/organize/settings-reference.mdx +++ b/organize/settings-reference.mdx @@ -223,7 +223,7 @@ Product switcher. Groups for organizing content into labeled sections. -**Type:** array of object +**Type:** array of object—each with: `group` (string, required), `root` (string), `directory` (`"none"` | `"accordion"` | `"card"`), `icon` (string), `iconType` (string), `expanded` (boolean), `pages` (array, required) #### `navigation.pages` diff --git a/organize/settings-structure.mdx b/organize/settings-structure.mdx index 9a90d9703..e6f85abe2 100644 --- a/organize/settings-structure.mdx +++ b/organize/settings-structure.mdx @@ -195,6 +195,25 @@ See [Navigation](/organize/navigation) for complete documentation on building yo [Groups](/organize/navigation#groups) for organizing content into sections. + + + + Display name of the group. Minimum length: 1. + + + Path to a root page for the group. When set, clicking the group title navigates to this page. See [Root page](/organize/navigation#root-page). + + + Directory listing style for the group's root page. When set to `accordion` or `card`, the root page automatically renders a listing of child pages below its content. The value inherits down to nested groups. Defaults to `"none"`. Requires `root` to be set. See [Directory listings](/organize/navigation#directory-listings). + + + + Whether a nested group is expanded by default. Only applies to groups within groups. See [Default expanded state](/organize/navigation#default-expanded-state). + + + Pages or nested groups within this group. + +