Skip to content
Closed
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
80 changes: 79 additions & 1 deletion 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 @@ -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
{
Expand Down Expand Up @@ -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.

Check warning on line 123 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L123

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

Check warning on line 124 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L124

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 127 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L127

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

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

Check warning on line 152 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L152

In general, use active voice instead of passive voice ('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.
Expand Down Expand Up @@ -380,9 +458,9 @@
}
```

## Dropdowns

Check warning on line 461 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L461

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 463 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L463

Use 'dropdowns?' instead of 'Dropdowns'.

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

</CodeGroup>

## Breadcrumbs

Check warning on line 1032 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L1032

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 1034 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L1034

Use 'breadcrumbs?' instead of 'Breadcrumbs'.

<CodeGroup>

Expand Down
6 changes: 6 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 @@ -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"`

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L232

Don't put a space before or after a dash.

#### `navigation.pages`

Individual pages in your documentation.
Expand Down Expand Up @@ -449,14 +455,14 @@

Code block theme configuration.

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L458

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 465 in organize/settings-reference.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L465

Did you really mean 'Shiki'?

**Type:** string or object

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L477

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 @@ -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>
Expand Down
Loading