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
4 changes: 2 additions & 2 deletions agent/customize.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ description: "Configure how the agent handles documentation tasks with AGENTS.md
keywords: ["AGENTS.md", "agent configuration", "custom instructions", "agent customization"]
---

Create an `AGENTS.md` file in your repository to customize the agent's behavior (`Agents.md` is also accepted). The agent reads this file and follows any instructions you provide.
Create an `AGENTS.md` file in your <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span> to customize the agent's behavior (`Agents.md` is also accepted). The agent reads this file and follows any instructions you provide.

The agent searches for `AGENTS.md` files in two locations. It first checks the documentation directory, then the repository root. If you have `AGENTS.md` files in both locations, the agent uses the file in your documentation directory.
The agent searches for `AGENTS.md` files in two locations. It first checks the documentation directory, then the <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span> root. If you have `AGENTS.md` files in both locations, the agent uses the file in your documentation directory.

Add any instructions that you want the agent to follow. The agent appends these instructions to its system prompt, so the instructions apply to all tasks, whether you use the agent in your dashboard, on Slack, or via the API.

Expand Down
6 changes: 3 additions & 3 deletions agent/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

## Open the agent panel

On desktop, the agent panel is resizable. On mobile devices, the agent opens in full-screen.

Check warning on line 9 in agent/quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

agent/quickstart.mdx#L9

Did you really mean 'resizable'?

To open the agent panel:

Expand All @@ -23,7 +23,7 @@
- **Chat**: Click the plus icon, <Icon icon="plus" />, to start a new chat. In the chat view, send prompts to the agent to update or ask questions about your documentation. The agent creates pull requests based on your instructions and displays links to view the pull requests or open the changes in the web editor.
- **Suggestions**: If enabled, the suggestions panel shows suggested updates to your documentation based on pull request changes and users' conversations with the assistant.
- **History**: Click the history icon, <Icon icon="clock" />, to browse past conversations and continue working on previous requests. Click any conversation to load it in the chat view.
- **Settings**: Click the settings icon, <Icon icon="settings" />, to configure the agent's integrations and repository access.
- **Settings**: Click the settings icon, <Icon icon="settings" />, to configure the agent's integrations and <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span> access.

<Tip>
Start a new conversation with the agent for each task. This keeps the agent's context focused and helps you associate conversations with specific projects.
Expand All @@ -33,6 +33,6 @@

By default, the agent opens pull requests attributed to the Mintlify bot. To attribute pull requests to you, connect your GitHub account on the [My profile](https://dashboard.mintlify.com/settings/account) page of the dashboard.

## Connect repositories as context
## Connect <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repositories</span> as context

The agent can only access repositories that you connect through the Mintlify GitHub App. Configure which repositories the agent can access in the agent panel **Settings** or in the [GitHub App settings](https://github.com/apps/mintlify/installations/new).
The agent can only access <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repositories</span> that you connect through the Mintlify GitHub App. Configure which <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repositories</span> the agent can access in the agent panel **Settings** or in the [GitHub App settings](https://github.com/apps/mintlify/installations/new).
2 changes: 1 addition & 1 deletion agent/slack.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
---

<Note>
If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify app before you connect it.

Check warning on line 8 in agent/slack.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

agent/slack.mdx#L8

Use 'administrator' instead of 'admin'.
</Note>

## Connect your Slack workspace
Expand Down Expand Up @@ -39,7 +39,7 @@
- **New request**: Send a direct message to the agent or mention `@mintlify` in a channel with instructions on what to update.
- **Existing thread**: Reply in the thread and mention `@mintlify` with instructions on what to update.

The agent reads the context of the request or thread and creates a pull request in your connected repository with the updates.
The agent reads the context of the request or thread and creates a pull request in your connected <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span> with the updates.

## Best practices

Expand Down
14 changes: 7 additions & 7 deletions agent/suggestions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

You can allow the agent to suggest documentation updates from two sources.

- **Pull request changes**: Monitor selected Git repositories for code changes that require documentation updates.
- **Pull request changes**: Monitor selected Git <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repositories</span> for code changes that require documentation updates.
- **Assistant conversations**: Analyze questions that users ask the assistant on your documentation site to identify content gaps.

When the agent identifies potential documentation updates, it creates a suggestion in your dashboard with context to create a pull request.
Expand All @@ -19,11 +19,11 @@

## Prerequisites

Before using suggestions, you must install the [Mintlify GitHub App](/deploy/github) in your organization. The app must have access to your documentation repository and at least one other repository where code changes require documentation updates.
Before using suggestions, you must install the [Mintlify GitHub App](/deploy/github) in your organization. The app must have access to your documentation <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span> and at least one other <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span> where code changes require documentation updates.

## Configure suggestions

Configure which repositories the agent monitors and how you receive notifications in the agent settings. The settings page displays all the GitHub organizations and repositories the agent is monitoring.
Configure which <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repositories</span> the agent monitors and how you receive notifications in the agent settings. The settings page displays all the GitHub organizations and <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repositories</span> the agent is monitoring.

To access the agent settings:

Expand All @@ -34,15 +34,15 @@
<img src="/images/agent/dashboard-settings-dark.png" alt="The settings button in dark mode." className="hidden dark:block" />
</Frame>

### Monitor repositories
### Monitor <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repositories</span>

The agent monitors all merged pull requests for each repository that you enable, regardless of which branch they're merged into. A GitHub check named **Mintlify Autopilot** runs on pull requests in monitored repositories to analyze them for potential documentation updates. When you merge a pull request that requires documentation updates, the agent creates a suggestion in your dashboard.
The agent monitors all merged pull requests for each <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span> that you enable, regardless of which branch they're merged into. A GitHub check named **Mintlify Autopilot** runs on pull requests in monitored <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repositories</span> to analyze them for potential documentation updates. When you merge a pull request that requires documentation updates, the agent creates a suggestion in your dashboard.

<Note>
When you first enable monitoring for a repository, the agent creates suggestions for pull requests merged in the last seven days. This backfill only occurs if no suggestions already exist for that repository. You may see multiple suggestions appear immediately after enabling monitoring.
When you first enable monitoring for a <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span>, the agent creates suggestions for pull requests merged in the last seven days. This backfill only occurs if no suggestions already exist for that <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span>. You may see multiple suggestions appear immediately after enabling monitoring.
</Note>

If you disable monitoring, the agent immediately stops monitoring the repository. Any existing suggestions for that repository remain in your dashboard until you dismiss them.
If you disable monitoring, the agent immediately stops monitoring the <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span>. Any existing suggestions for that <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span> remain in your dashboard until you dismiss them.

Check warning on line 45 in agent/suggestions.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

agent/suggestions.mdx#L45

Use 'turn off' or 'off' instead of 'disable'.

### Conversation insights

Expand Down
2 changes: 1 addition & 1 deletion ai/llmstxt.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "llms.txt"
description: "Optimize your docs for LLMs to read and index."
keywords: ["llms.txt", "LLM indexing", "AEO", "GEO", "content discovery"]

Check warning on line 4 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L4

Use 'LLMs' instead of 'llms'.
---

import { PreviewButton } from "/snippets/previewbutton.jsx"
Expand All @@ -16,16 +16,16 @@

View your `llms.txt` by appending `/llms.txt` to your documentation site's URL.

<PreviewButton href="https://mintlify.com/docs/llms.txt">Open the llms.txt for this site.</PreviewButton>

Check warning on line 19 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L19

Use 'LLMs' instead of 'llms'.

## llms.txt structure

Check warning on line 21 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L21

'llms.txt structure' should use sentence-style capitalization.

Check warning on line 21 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L21

Use 'LLMs' instead of 'llms'.

An `llms.txt` file is a plain Markdown file that contains:

- **Site title** as an H1 heading.
- **Structured content sections** with links and a description of each page in your documentation.

Pages are listed alphabetically in the order they appear in your repository, starting from the root directory.
Pages are listed alphabetically in the order they appear in your <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span>, starting from the root directory.

Check warning on line 28 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L28

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

Each page's description comes from the `description` field in its frontmatter. Pages without a `description` field appear in the `llms.txt` file without a description.

Expand All @@ -41,16 +41,16 @@

This structured approach allows LLMs to efficiently process your documentation at a high level and locate relevant content for user queries, improving the accuracy and speed of AI-assisted documentation searches.

## llms-full.txt

Check warning on line 44 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L44

Use 'LLMs' instead of 'llms'.

Check warning on line 44 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L44

'llms-full.txt' should use sentence-style capitalization.

The `llms-full.txt` file combines your entire documentation site into a single file as context for AI tools and is indexed by LLM traffic.

Check warning on line 46 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L46

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

Mintlify automatically hosts an `llms-full.txt` file at the root of your project. View your `llms-full.txt` by appending `/llms-full.txt` to your documentation site's URL.

<PreviewButton href="https://mintlify.com/docs/llms-full.txt">Open the llms-full.txt for this site.</PreviewButton>

Check warning on line 50 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L50

Use 'LLMs' instead of 'llms'.

## Custom files

To add a custom `llms.txt` or `llms-full.txt` file, create an `llms.txt` or `llms-full.txt` file at the root of your project. Adding a custom file will override the automatically generated file of the same name. If you delete a custom file, the default file will be used again.

Check warning on line 54 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L54

Avoid using 'will'.

Check warning on line 54 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L54

Avoid using 'will'.

Check warning on line 54 in ai/llmstxt.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/llmstxt.mdx#L54

In general, use active voice instead of passive voice ('be used').

Your custom `llms.txt` or `llms-full.txt` file must have a site title as an H1 heading. Other content is optional. See [Format](https://llmstxt.org/#format) in the `llms.txt` specification for more information on optional sections and best practices.
2 changes: 1 addition & 1 deletion ai/model-context-protocol.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@

### How MCP servers work

When an AI application connects to your documentation MCP server, it can search your documentation directly instead of making a generic web search in response to a user's prompt. Your MCP server provides access to all indexed content on your documentation site.

Check warning on line 17 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L17

Use 'app' instead of 'application'.

- The AI application can proactively search your documentation while generating a response, not just when explicitly asked.

Check warning on line 19 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L19

Use 'app' instead of 'application'.
- The AI application determines when to use the search tool based on the context of the conversation and the relevance of your documentation.

Check warning on line 20 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L20

Use 'app' instead of 'application'.
- Each search (tool call) happens during the generation process, so the AI application searches up-to-date information from your documentation to generate its response.

Check warning on line 21 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L21

Use 'app' instead of 'application'.

<Tip>
Some AI tools like Claude support both MCP and Skills. MCP gives the AI access to your documentation content, while Skills instruct the AI how to use that content effectively. They're complementary. MCP provides the data and Skills provide the instructions.
Expand All @@ -31,7 +31,7 @@
- **`version`**: Filter results to a specific documentation version. For example, `'v0.7'`. Only returns content tagged with the specified version or content available across all versions.
- **`language`**: Filter results to a specific language code. For example, `'en'`, `'zh'`, or `'es'`. Only returns content in the specified language or content available across all languages.

AI applications determine when to apply these filters based on the context of the user's query. For example, if a user asks about a specific API version, the AI application may automatically apply the appropriate filter to provide more relevant results.

Check warning on line 34 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L34

Use 'app' instead of 'application'.

### MCP compared to web search

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

## Content filtering and indexing

Your MCP server searches content that Mintlify indexes from your documentation repository. File processing and search indexing control what content is available through your MCP server.
Your MCP server searches content that Mintlify indexes from your documentation <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span>. File processing and search indexing control what content is available through your MCP server.

### File processing with `.mintignore`

Expand Down
2 changes: 1 addition & 1 deletion api-playground/mdx-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@
}
```

Each page path corresponds to an MDX file in your docs repository. For example, `api-reference/users/create-user.mdx`. Learn more about structuring your docs in [Navigation](/organize/navigation).
Each page path corresponds to an MDX file in your docs <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span>. For example, `api-reference/users/create-user.mdx`. Learn more about structuring your docs in [Navigation](/organize/navigation).

### Using OpenAPI endpoints in navigation

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

### None

To disable authentication on a specific page, set `authMethod` to `none`:

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/mdx-setup.mdx#L248

Use 'turn off' or 'off' instead of 'disable'.

```mdx Page Metadata
---
Expand Down
2 changes: 1 addition & 1 deletion api-playground/openapi-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

To document your endpoints with OpenAPI, you need one or more valid OpenAPI specifications in either JSON or YAML format that follow the [OpenAPI specification 3.0 or 3.1](https://swagger.io/specification/).

Add OpenAPI specifications to your documentation repository or host them online where you can access the specifications by URL.
Add OpenAPI specifications to your documentation <span style={{ backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #4b0082, #9400d3)', backgroundClip: 'text', WebkitBackgroundClip: 'text', WebkitTextFillColor: 'transparent' }}>repository</span> or host them online where you can access the specifications by URL.

Reference any number of OpenAPI specifications in the navigation element of your `docs.json` to create pages for your API endpoints. Each specification file generates its own set of endpoints.

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

## 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

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

### Href

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L211

Use 'href' instead of 'Href'.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L211

'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 +239,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 242 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L242

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 246 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L246

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 +259,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 262 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L262

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

```json {5}
"navigation": {
Expand Down Expand Up @@ -301,7 +301,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 304 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L304

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

### Selective endpoints
Expand Down Expand Up @@ -340,7 +340,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 343 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L343

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

```json {3, 7-8, 11, 13-14}
{
Expand All @@ -365,7 +365,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 368 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L368

Use 'path' instead of 'file path'.

```json {5-6}
"navigation": {
Expand Down Expand Up @@ -417,9 +417,9 @@

</CodeGroup>

The method and path must exactly match your OpenAPI spec. If you have multiple OpenAPI specifications, include the file path in your reference. External OpenAPI URLs can be referenced in `docs.json`.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L420

Use 'path' instead of 'file path'.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L420

In general, use active voice instead of passive voice ('be referenced').

#### Autogenerate endpoint pages

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L422

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 All @@ -428,7 +428,7 @@
```

<Tip>
Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files will populate in the working directory.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L431

Avoid using 'will'.
</Tip>

### Document data models
Expand Down Expand Up @@ -471,7 +471,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 474 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L474

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
Loading