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
29 changes: 29 additions & 0 deletions api-playground/openapi-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -130,9 +130,9 @@

## Customize your endpoint pages

Customize your endpoint pages by adding the `x-mint` extension to your OpenAPI specification. The `x-mint` extension provides additional control over how your API documentation is generated and displayed.

Check warning on line 133 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L133

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

### Metadata

Check warning on line 135 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L135

Use 'metadata' instead of 'Metadata'.

Check warning on line 135 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L135

'Metadata' should use sentence-style capitalization.

Override the default metadata for generated API pages by adding `x-mint: metadata` to any operation. You can use any metadata field that would be valid in MDX frontmatter except for `openapi`.

Expand Down Expand Up @@ -208,7 +208,36 @@
}
```

### MCP

Control how individual endpoints are exposed as MCP (Model Context Protocol) tools using `x-mint: mcp`. This lets you enable or disable MCP exposure per endpoint and customize the tool name and description.

Check warning on line 213 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L213

In general, use active voice instead of passive voice ('are exposed').

```json {6-11}
{
"paths": {
"/users": {
"get": {
"summary": "Get users",
"x-mint": {
"mcp": {
"enabled": true,
"name": "list_users",
"description": "Retrieve a paginated list of all users"
}
}
}
}
}
}
```

| Field | Type | Description |
|---|---|---|
| `enabled` | boolean | Whether the endpoint is exposed as an MCP tool. |

Check warning on line 236 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L236

In general, use active voice instead of passive voice ('is exposed').
| `name` | string | Custom name for the MCP tool. |
| `description` | string | Custom description for the MCP tool. |

### Href

Check warning on line 240 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L240

Use 'href' instead of 'Href'.

Check warning on line 240 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L240

'Href' should use sentence-style capitalization.

Set the URL of the autogenerated endpoint page using `x-mint: href`. When `x-mint: href` is present, the generated API page uses the specified URL instead of the default autogenerated URL.

Expand Down Expand Up @@ -239,11 +268,11 @@

Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.

The `openapi` field accepts either a file path in your docs repo or a URL to a hosted OpenAPI document.

Check warning on line 271 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L271

Use 'path' instead of 'file path'.

Generated endpoint pages have these default metadata values:

- `title`: The operation's `summary` field, if present. If there is no `summary`, the title is generated from the HTTP method and endpoint.

Check warning on line 275 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L275

In general, use active voice instead of passive voice ('is generated').
- `description`: The operation's `description` field, if present.
- `version`: The `version` value from the parent anchor or tab, if present.
- `deprecated`: The operation's `deprecated` field. If `true`, a deprecated label appears next to the endpoint title in the side navigation and on the endpoint page.
Expand All @@ -259,7 +288,7 @@

### Dedicated API sections

Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. All endpoints in the specification are included.

Check warning on line 291 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L291

In general, use active voice instead of passive voice ('are included').

```json {5}
"navigation": {
Expand Down Expand Up @@ -301,7 +330,7 @@
```

<Note>
The `directory` field is optional and specifies where generated API pages are stored in your docs repo. If not specified, defaults to the `api-reference` directory of your repo.

Check warning on line 333 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L333

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

### Selective endpoints
Expand Down Expand Up @@ -340,7 +369,7 @@

#### OpenAPI spec inheritance

OpenAPI specifications are inherited down the navigation hierarchy. Child navigation elements inherit their parent's OpenAPI specification unless they define their own.

Check warning on line 372 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L372

In general, use active voice instead of passive voice ('are inherited').

```json {3, 7-8, 11, 13-14}
{
Expand All @@ -365,7 +394,7 @@

#### Individual endpoints

Reference specific endpoints without setting a default OpenAPI specification by including the file path. You can reference endpoints from multiple OpenAPI specifications in the same documentation section.

Check warning on line 397 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L397

Use 'path' instead of 'file path'.

```json {5-6}
"navigation": {
Expand Down Expand Up @@ -419,7 +448,7 @@

The method and path must exactly match your OpenAPI spec. If you have multiple OpenAPI specifications, include the path to the correct specification in your reference. You can also reference external OpenAPI URLs in `docs.json`.

#### Autogenerate endpoint pages

Check warning on line 451 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L451

Use 'autogenerat(e|ed|ing)?' instead of 'Autogenerate'.

To autogenerate MDX files from your OpenAPI specification, use the Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping).

Expand Down Expand Up @@ -471,7 +500,7 @@

## Webhooks

Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. Webhooks are supported in OpenAPI 3.1+ documents.

Check warning on line 503 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L503

In general, use active voice instead of passive voice ('are supported').

Add a `webhooks` field to your OpenAPI document alongside the `paths` field.

Expand Down
14 changes: 10 additions & 4 deletions organize/navigation.mdx
Original file line number Diff line number Diff line change
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 Down Expand Up @@ -159,6 +159,8 @@

In the `navigation` object, `tabs` is an array where each entry is an object that requires a `tab` field and can contain other navigation fields such as groups, pages, icons, or links to external pages.

Set `align` to `"end"` to push a tab to the right side of the tab bar. Tabs default to `"start"` alignment.

```json
{
"navigation": {
Expand All @@ -184,6 +186,7 @@
{
"tab": "Blog",
"icon": "newspaper",
"align": "end",
"href": "https://external-link.com/blog"
}
]
Expand Down Expand Up @@ -332,16 +335,18 @@

Products create a dedicated navigation division for organizing product-specific documentation. Use products to separate different offerings, services, or major feature sets within your documentation.

In the `navigation` object, `products` is an array where each entry is an object that requires a `product` field and can contain other navigation fields such as groups, pages, icons, or links to external pages.
In the `navigation` object, `products` is an array where each entry is an object that requires a `product` field and can contain other navigation fields such as groups, pages, icons, or links to external pages. Set `name` to override the display name shown in the product switcher. Set `color` to a hex code or a `{ light, dark }` object to customize the product accent color.

```json
{
"navigation": {
"products": [
{
"product": "Core API",
"description": "Core API description",
"name": "API",
"description": "Core API description",
"icon": "api",
"color": "#6366f1",
"groups": [
{
"group": "Getting started",
Expand Down Expand Up @@ -396,7 +401,7 @@
alt="Decorative graphic of a dropdown navigation."
/>

In the `navigation` object, `dropdowns` is an array where each entry is an object that requires a `dropdown` field and can contain other navigation fields such as groups, pages, icons, or links to external pages.
In the `navigation` object, `dropdowns` is an array where each entry is an object that requires a `dropdown` field and can contain other navigation fields such as groups, pages, icons, or links to external pages. Set `description` to add helper text below the dropdown label. Set `color` to a hex code or a `{ light, dark }` object to customize the dropdown accent color.

```json
{
Expand All @@ -405,6 +410,7 @@
{
"dropdown": "Documentation",
"icon": "book-open",
"description": "Guides and reference material",
"pages": [
"quickstart",
"development",
Expand Down Expand Up @@ -636,7 +642,7 @@
<Card title="Spanish (es)" icon="/images/navigation/languages/es.png" horizontal />
<Card title="Swedish (sv)" icon="/images/navigation/languages/sv.png" horizontal />
<Card title="Turkish (tr)" icon="/images/navigation/languages/tr.png" horizontal />
<Card title="Ukrainian (ua)" icon="/images/navigation/languages/ua.png" horizontal />
<Card title="Ukrainian (uk)" icon="/images/navigation/languages/ua.png" horizontal />
<Card title="Uzbek (uz)" icon="/images/navigation/languages/uz.png" horizontal />
<Card title="Vietnamese (vi)" icon="/images/navigation/languages/vi.png" horizontal />
</CardGroup>
Expand Down Expand Up @@ -950,9 +956,9 @@

</CodeGroup>

## Breadcrumbs

Check warning on line 959 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L959

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L961

Use 'breadcrumbs?' instead of 'Breadcrumbs'.

<CodeGroup>

Expand Down
6 changes: 3 additions & 3 deletions organize/settings-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -95,19 +95,19 @@

The primary color. Generally used for emphasis in light mode.

**Type:** string — hex code matching `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$`

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L98

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

#### `colors.light`

The color used for emphasis in dark mode.

**Type:** string — hex code matching `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$`

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L104

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

#### `colors.dark`

The color used for buttons and hover states across both modes.

**Type:** string — hex code matching `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$`

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L110

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

---

Expand All @@ -129,25 +129,25 @@

Top-level navigation tabs.

**Type:** array of object — each with: `tab` (string, required), `icon` (string), `iconType` (string), `hidden` (boolean), `href` (string uri, required)
**Type:** array of object — each with: `tab` (string, required), `icon` (string), `iconType` (string), `hidden` (boolean), `align` (`"start"` | `"end"`), `href` (string uri, required)

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L132

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

##### `navigation.global.anchors`

Sidebar anchor links.

**Type:** array of object — each with: `anchor` (string, required), `icon` (string), `iconType` (string), `color.light` (string hex), `color.dark` (string hex), `hidden` (boolean), `href` (string uri, required)

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L138

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

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

Dropdown menus.

**Type:** array of object — each with: `dropdown` (string, required), `icon` (string), `iconType` (string), `hidden` (boolean), `href` (string uri, required)
**Type:** array of object — each with: `dropdown` (string, required), `icon` (string), `iconType` (string), `description` (string), `color` (string hex or `{ light, dark }` object), `hidden` (boolean), `href` (string uri, required)

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L144

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

##### `navigation.global.languages`

Language switcher in the global nav.

**Type:** array of object — each with: `language` (string, required), `default` (boolean), `hidden` (boolean), `href` (string uri, required)

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L150

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

**Supported language codes:** `ar`, `ca`, `cn`, `cs`, `de`, `en`, `es`, `fr`, `fr-CA`, `he`, `hi`, `hu`, `id`, `it`, `ja`, `jp`, `ko`, `lv`, `nl`, `no`, `pl`, `pt`, `pt-BR`, `ro`, `ru`, `sv`, `tr`, `uk`, `uz`, `vi`, `zh`, `zh-Hans`, `zh-Hant`

Expand All @@ -155,19 +155,19 @@

Version switcher in the global nav.

**Type:** array of object — each with: `version` (string, required, min length 1), `default` (boolean), `hidden` (boolean), `href` (string uri, required)

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L158

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

##### `navigation.global.products`

Product switcher in the global nav.

**Type:** array of object — each with: `product` (string, required), `description` (string), `icon` (string), `iconType` (string)
**Type:** array of object — each with: `product` (string, required), `name` (string), `description` (string), `icon` (string), `iconType` (string), `color` (string hex or `{ light, dark }` object), `hidden` (boolean)

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L164

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

#### `navigation.languages`

Language switcher for multi-language sites. Each entry can include language-specific `banner`, `footer`, and `navbar` overrides.

**Type:** array of object — each with: `language` (string, required), `default` (boolean), `hidden` (boolean), `banner` (object), `footer` (object), `navbar` (object)

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L170

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

**Supported language codes:** `ar`, `ca`, `cn`, `cs`, `de`, `en`, `es`, `fr`, `fr-CA`, `he`, `hi`, `hu`, `id`, `it`, `ja`, `jp`, `ko`, `lv`, `nl`, `no`, `pl`, `pt`, `pt-BR`, `ro`, `ru`, `sv`, `tr`, `uk`, `uz`, `vi`, `zh`, `zh-Hans`, `zh-Hant`

Expand All @@ -175,31 +175,31 @@

Version switcher for multi-version sites.

**Type:** array of object — each with: `default` (boolean), `tag` (string)

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L178

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

#### `navigation.tabs`

Top-level navigation tabs.

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L184

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

#### `navigation.anchors`

Sidebar anchor links.

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L190

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

#### `navigation.dropdowns`

Dropdown menus.

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L196

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

#### `navigation.products`

Product switcher.

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

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L202

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

#### `navigation.groups`

Expand Down Expand Up @@ -378,13 +378,13 @@

Background color for light mode.

**Type:** string — hex code matching `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$`

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L381

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

##### `background.color.dark`

Background color for dark mode.

**Type:** string — hex code matching `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$`

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L387

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

#### `background.image`

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

Links displayed in the navbar.

**Type:** array of object — each with:

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L503

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

| Field | Type | Required | Description |
|---|---|---|---|
Expand Down Expand Up @@ -542,7 +542,7 @@

Link columns in the footer.

**Type:** array of object — each with: `header` (string), `items` (array of `{ label: string, href: string }`, required)

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L545

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

---

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

Redirects for moved, renamed, or deleted pages.

**Type:** array of object — each with:

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L625

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

| Field | Type | Required | Description |
|---|---|---|---|
Expand All @@ -636,7 +636,7 @@

Global content variables replaced at build time using `{{variableName}}` syntax.

**Type:** object — key-value pairs where keys are variable names (alphanumeric, hyphens, periods) and values are replacement strings.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings-reference.mdx#L639

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

---

Expand Down
Loading