Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions organize/navigation.mdx
Original file line number Diff line number Diff line change
@@ -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."

Check warning on line 3 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L3

Use 'JSON' instead of 'json'.
keywords: ["navigation structure", "sidebar configuration", "page organization", "navigation groups"]
---

Expand Down Expand Up @@ -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.

Check warning on line 178 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L178

In general, use active voice instead of passive voice ('is expanded').
- `expanded: false` or omitted: Group is collapsed by default.

Check warning on line 179 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L179

In general, use active voice instead of passive voice ('is collapsed').

<Note>
The `expanded` property only affects nested groups--groups within groups. Top-level groups are always expanded and cannot be collapsed.

Check warning on line 182 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L182

In general, use active voice instead of passive voice ('be collapsed').
</Note>

```json
Expand Down Expand Up @@ -380,9 +435,9 @@
}
```

## Dropdowns

Check warning on line 438 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L438

Use 'dropdowns?' instead of '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.

Check warning on line 440 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L440

Use 'dropdowns?' instead of 'Dropdowns'.

<img
className="block dark:hidden pointer-events-none"
Expand Down Expand Up @@ -951,9 +1006,9 @@

</CodeGroup>

## Breadcrumbs

Check warning on line 1009 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L1009

Use 'breadcrumbs?' instead of '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`.

Check warning on line 1011 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L1011

Use 'breadcrumbs?' instead of 'Breadcrumbs'.

<CodeGroup>

Expand Down
7 changes: 7 additions & 0 deletions organize/settings-reference.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "docs.json schema reference"

Check warning on line 2 in organize/settings-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L2

Use 'JSON' instead of 'json'.
description: "Complete reference for every docs.json configuration property with types, default values, descriptions, and usage examples for your docs site."

Check warning on line 3 in organize/settings-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L3

Use 'JSON' instead of 'json'.
keywords: ["docs.json", "schema", "reference", "configuration", "all settings", "properties", "complete"]
---

Expand Down Expand Up @@ -157,7 +157,7 @@

##### `navigation.global.dropdowns`

Dropdown menus.

Check warning on line 160 in organize/settings-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L160

Use 'dropdowns?' instead of 'Dropdown'.

**Type:** array of object—each with: `dropdown` (string, required), `icon` (string), `iconType` (string), `hidden` (boolean), `href` (string uri, required)

Expand Down Expand Up @@ -209,7 +209,7 @@

#### `navigation.dropdowns`

Dropdown menus.

Check warning on line 212 in organize/settings-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L212

Use 'dropdowns?' instead of 'Dropdown'.

**Type:** array of object—see `navigation.global.dropdowns` for shape.

Expand All @@ -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.

Check warning on line 236 in organize/settings-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L236

Use semicolons judiciously.

**Type:** `"none"` | `"accordion"` | `"card"`
**Default:** `"none"`

---

### `description`
Expand Down Expand Up @@ -449,14 +456,14 @@

Code block theme configuration.

**Type:** `"system"` | `"dark"` | string (Shiki theme name) | object

Check warning on line 459 in organize/settings-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L459

Did you really mean 'Shiki'?
**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.

Check warning on line 466 in organize/settings-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L466

Did you really mean 'Shiki'?

**Type:** string or object

Expand All @@ -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).

Check warning on line 478 in organize/settings-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L478

Did you really mean 'Shiki'?

**Type:** array of string

Expand Down
4 changes: 4 additions & 0 deletions organize/settings-structure.mdx
Original file line number Diff line number Diff line change
@@ -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."

Check warning on line 3 in organize/settings-structure.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-structure.mdx#L3

Use 'JSON' instead of 'json'.
keywords: ["navbar", "navigation", "footer", "banner", "contextual", "redirects", "variables", "metadata", "docs.json"]
---

Expand Down Expand Up @@ -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.

Check warning on line 205 in organize/settings-structure.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-structure.mdx#L205

Use semicolons judiciously.
</ResponseField>

---

### `navbar`
Expand Down
Loading