Skip to content
Open
95 changes: 95 additions & 0 deletions api-playground/adding-sdk-examples.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@

If your users interact with your API using an SDK rather than directly through a network request, you can use the `x-codeSamples` extension to add code samples to your OpenAPI document and display them in your OpenAPI pages.

SDK examples appear alongside the default cURL examples in your API playground, making it easier for developers to integrate with your API using their preferred language or framework.

This property can be added to any request method and has the following schema.

Check warning on line 11 in api-playground/adding-sdk-examples.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/adding-sdk-examples.mdx#L11

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

<ParamField body="lang" type="string" required>
The language of the code sample.
Expand All @@ -20,7 +22,7 @@
The source code of the sample.
</ParamField>

Here is an example of code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK.

Check warning on line 25 in api-playground/adding-sdk-examples.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/adding-sdk-examples.mdx#L25

Use 'command-line tool' instead of 'CLI'.

```yaml
paths:
Expand Down Expand Up @@ -48,3 +50,96 @@
planter.list({ potted: true });
```

## Multiple SDK languages

Check warning on line 53 in api-playground/adding-sdk-examples.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/adding-sdk-examples.mdx#L53

'Multiple SDK languages' should use sentence-style capitalization.

You can provide examples in multiple programming languages to support different developer audiences. Common languages include:

<CodeGroup>

```yaml Python example
x-codeSamples:
- lang: python
label: Get user by ID
source: |
import requests

response = requests.get(
'https://api.example.com/users/123',
headers={'Authorization': 'Bearer YOUR_TOKEN'}
)
user = response.json()
```

```yaml JavaScript example
x-codeSamples:
- lang: javascript
label: Get user by ID
source: |
const response = await fetch('https://api.example.com/users/123', {
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
});
const user = await response.json();
```

```yaml Go example
x-codeSamples:
- lang: go
label: Get user by ID
source: |
client := &http.Client{}
req, _ := http.NewRequest("GET", "https://api.example.com/users/123", nil)
req.Header.Add("Authorization", "Bearer YOUR_TOKEN")
resp, _ := client.Do(req)
```

```yaml Ruby example
x-codeSamples:
- lang: ruby
label: Get user by ID
source: |
require 'net/http'
require 'json'

uri = URI('https://api.example.com/users/123')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer YOUR_TOKEN'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(req)
end
user = JSON.parse(response.body)
```

</CodeGroup>

## Best practices

<AccordionGroup>
<Accordion title="Use realistic examples">
Provide examples that reflect actual use cases rather than placeholder code. Include error handling and common patterns your users will need.

Check warning on line 120 in api-playground/adding-sdk-examples.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/adding-sdk-examples.mdx#L120

Avoid using 'will'.
</Accordion>

<Accordion title="Keep examples concise">
Focus on the essential code needed to make the API call. Avoid unnecessary boilerplate that distracts from the core functionality.

Check warning on line 124 in api-playground/adding-sdk-examples.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/adding-sdk-examples.mdx#L124

Use 'capability' or 'feature' instead of 'functionality'.
</Accordion>

<Accordion title="Match your SDK">
If you provide official SDKs, ensure the examples match your SDK's actual API and conventions. Keep examples updated when your SDK changes.
</Accordion>

<Accordion title="Include authentication">
Show how to properly authenticate requests in each language, as authentication patterns vary significantly across SDKs.
</Accordion>

<Accordion title="Add helpful labels">
Use descriptive labels when providing multiple examples for the same endpoint to help users find the right example quickly.
</Accordion>
</AccordionGroup>

## Related resources

<Card title="Learn more about OpenAPI setup" icon="code" href="/api-playground/openapi-setup">
Configure OpenAPI specifications and generate API documentation
</Card>

4 changes: 4 additions & 0 deletions create/code.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@

You can add inline code snippets or code blocks. Code blocks support meta options for syntax highlighting, titles, line highlighting, icons, and more.

<Card title="Learn more about text formatting" icon="text" href="/create/text">
Format text, create headers, and style content
</Card>

### Inline code

To denote a `word` or `phrase` as code, enclose it in backticks (\`).
Expand Down Expand Up @@ -146,7 +150,7 @@

</Accordion>

### Twoslash

Check warning on line 153 in create/code.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/code.mdx#L153

Did you really mean 'Twoslash'?

In JavaScript and TypeScript code blocks, use `twoslash` to enable interactive type information. Users can hover over variables, functions, and parameters to see types and errors like in an IDE.

Expand Down
4 changes: 4 additions & 0 deletions create/text.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@

Headers organize your content and create navigation anchors. They appear in the table of contents and help users scan your documentation.

<Card title="Learn more about code formatting" icon="code" href="/create/code">
Display and style inline code and code blocks
</Card>

### Creating headers

Use `#` symbols to create headers of different levels:
Expand All @@ -24,7 +28,7 @@

### Disabling anchor links

By default, headers include clickable anchor links that allow users to link directly to specific sections. You can disable these anchor links using the `noAnchor` prop in HTML or React headers.

Check warning on line 31 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L31

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

<CodeGroup>

Expand All @@ -42,11 +46,11 @@

</CodeGroup>

When `noAnchor` is used, the header will not display the anchor chip and clicking the header text will not copy the anchor link to the clipboard.

Check warning on line 49 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L49

Use 'won't' instead of 'will not'.

Check warning on line 49 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L49

Avoid using 'will'.

Check warning on line 49 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L49

Use 'won't' instead of 'will not'.

Check warning on line 49 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L49

Avoid using 'will'.

## Text formatting

We support most Markdown formatting for emphasizing and styling text.

Check warning on line 53 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L53

Try to avoid using first-person plural like 'We'.

### Basic formatting

Expand Down Expand Up @@ -120,7 +124,7 @@

Blockquotes highlight important information, quotes, or examples within your content.

### Single line blockquotes

Check warning on line 127 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L127

'Single line blockquotes' should use sentence-style capitalization.

Add `>` before text to create a blockquote:

Expand All @@ -130,7 +134,7 @@

> This is a quote that stands out from the main content.

### Multi-line blockquotes

Check warning on line 137 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L137

'Multi-line blockquotes' should use sentence-style capitalization.

For longer quotes or multiple paragraphs:

Expand All @@ -150,14 +154,14 @@

## Mathematical expressions

We support LaTeX for rendering mathematical expressions and equations. You can override automated detection by configuring `styles.latex` in your `docs.json` [settings](/organize/settings#param-latex).

Check warning on line 157 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L157

Try to avoid using first-person plural like 'We'.

### Inline math

Use single dollar signs, `$`, for inline mathematical expressions:

```mdx
The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.

Check warning on line 164 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L164

Use parentheses judiciously.
```

The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.
Expand Down Expand Up @@ -218,7 +222,7 @@

### Content organization
- Use headers to create clear content hierarchy
- Follow proper header hierarchy (don't skip from H2 to H4)

Check warning on line 225 in create/text.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/text.mdx#L225

Use parentheses judiciously.
- Write descriptive, keyword-rich header text

### Text formatting
Expand Down
4 changes: 4 additions & 0 deletions deploy/ci.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,16 @@

Use CI checks to lint your docs for errors and provide warnings before you deploy. Mintlify CI checks run on pull requests against a configured deployment branch.

<Card title="Learn more about GitHub deployments" icon="github" href="/deploy/github">
Connect to a GitHub repository for automated deployments and pull request previews
</Card>

## Installation

To begin, follow the steps on the [GitHub](/deploy/github) page.

<Tip>
Only access to the repository where your documentation content exists is required, so it is highly recommended to only grant access to that repository.

Check warning on line 22 in deploy/ci.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ci.mdx#L22

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

Check warning on line 22 in deploy/ci.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ci.mdx#L22

Use 'it's' instead of 'it is'.
</Tip>

## Configuration
Expand All @@ -24,8 +28,8 @@

When enabling checks, you can choose to run them at a `Warning` or `Blocking` level.

- A `Warning` level check will never provide a failure status, even if there is an error or suggestions.

Check warning on line 31 in deploy/ci.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ci.mdx#L31

Avoid using 'will'.
- A `Blocking` level check will provide a failure status if there is an error or suggestions.

Check warning on line 32 in deploy/ci.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ci.mdx#L32

Avoid using 'will'.

## Available CI checks

Expand Down Expand Up @@ -355,8 +359,8 @@

To add your own vocabulary for the default configuration, create a `styles/config/vocabularies/Mintlify` directory with `accept.txt` and `reject.txt` files.

- `accept.txt`: Words that should be ignored by the Vale linter. For example, product names or uncommon terms.

Check warning on line 362 in deploy/ci.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ci.mdx#L362

In general, use active voice instead of passive voice ('be ignored').
- `reject.txt`: Words that should be flagged as errors. For example, jargon or words that are not appropriate for the tone of your documentation.

Check warning on line 363 in deploy/ci.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ci.mdx#L363

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

Check warning on line 363 in deploy/ci.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ci.mdx#L363

Use 'aren't' instead of 'are not'.

```text Example Vale file structure
/your-project
Expand Down Expand Up @@ -394,12 +398,12 @@
</Note>

#### Packages
Vale supports a range of [packages](https://vale.sh/docs/keys/packages), which can be used to check for spelling and style errors. Any packages you include in your repository under the correct `stylesPath` are automatically installed and used in your Vale configuration.

Check warning on line 401 in deploy/ci.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ci.mdx#L401

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

For packages not included in your repository, you may specify any packages from the [Vale package registry](https://vale.sh/explorer), and they're automatically downloaded and used in your Vale configuration.

<Note>
For security reasons, automatically downloading packages that aren't from the [Vale package registry](https://vale.sh/explorer) is **not** supported.

Check warning on line 406 in deploy/ci.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ci.mdx#L406

Use 'isn't' instead of 'is not'.
</Note>

#### Vale with `MDX`
Expand All @@ -413,9 +417,9 @@
```mdx
{/* vale off */}

This text is ignored by Vale

Check warning on line 420 in deploy/ci.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ci.mdx#L420

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

{/* vale on */}
```

Vale automatically recognizes and respects these comments in MDX files without additional configuration. Use comments to skip lines or sections that should be ignored by the linter.

Check warning on line 425 in deploy/ci.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ci.mdx#L425

In general, use active voice instead of passive voice ('be ignored').
4 changes: 4 additions & 0 deletions deploy/github.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,13 @@
See your repository in the [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page of your dashboard.
</Tip>

<Card title="Learn more about CI deployments" icon="gears" href="/deploy/ci">
Deploy from CI/CD pipelines with GitHub Actions, GitLab CI, and more
</Card>

If your repository is in the `mintlify-community` organization, the GitHub App is automatically configured and managed by Mintlify. You can use the web editor to make changes to your documentation. If you want to work on your documentation locally, clone the repository to your own organization and update your Git settings to use your own repository.

## Install the GitHub App

Check warning on line 24 in deploy/github.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/github.mdx#L24

'Install the GitHub App' should use sentence-style capitalization.

<Note>
You must have organization ownership or administrator permissions in a repository to install the app. If you lack the necessary permissions, the repository owner must approve the installation request.
Expand All @@ -26,7 +30,7 @@
Install the Mintlify GitHub App through your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app).

<Tip>
We recommend only granting access to your documentation repository.

Check warning on line 33 in deploy/github.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/github.mdx#L33

Try to avoid using first-person plural like 'We'.
</Tip>

<Frame>
Expand All @@ -52,15 +56,15 @@

## Manage repository access

When installing the GitHub App, you can grant access to all of your repositories or specific ones. We recommend only granting access to your documentation repository and any repositories that you want to provide as context for the agent. You can modify this selection anytime in your [GitHub App settings](https://github.com/apps/mintlify/installations/new).

Check warning on line 59 in deploy/github.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/github.mdx#L59

Try to avoid using first-person plural like 'We'.

## Configure docs source

Change the organization, repository, or branch that your documentation builds from in the [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) section of your dashboard.

## GitHub Enterprise with IP allowlists

Check warning on line 65 in deploy/github.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/github.mdx#L65

Did you really mean 'allowlists'?

If your GitHub Enterprise Cloud organization has an IP allowlist enabled, you need to add Mintlify's egress IP address (`54.242.90.151`) to your allowlist for the GitHub App to function properly.

Check warning on line 67 in deploy/github.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/github.mdx#L67

Use 'Google Cloud Platform' or 'GCP' instead of 'Cloud'.

Follow [GitHub's documentation](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) to configure your IP allowlist.

Expand All @@ -84,7 +88,7 @@
</Accordion>
</AccordionGroup>

### GitHub App connection issues

Check warning on line 91 in deploy/github.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/github.mdx#L91

'GitHub App connection issues' should use sentence-style capitalization.

If you encounter problems with the GitHub app, resetting the connection can solve most problems.

Expand All @@ -101,7 +105,7 @@

### Feedback add-ons are unavailable

If you cannot enable the edit suggestions or raise issues options in your dashboard and your repository is public, revalidate your Git settings.

Check warning on line 108 in deploy/github.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/github.mdx#L108

Use 'can't' instead of 'cannot'.

<Steps>
<Step title="Navigate to Git Settings">
Expand Down
3 changes: 2 additions & 1 deletion docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,8 @@
"group": "Overview",
"icon": "book-open",
"pages": [
"guides/index"
"guides/index",
"guides/common-tasks"
]
},
{
Expand Down
177 changes: 177 additions & 0 deletions guides/common-tasks.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
---
title: "Common tasks"
description: "Quick reference for frequently performed documentation tasks."
keywords: ["quick reference", "common tasks", "how-to", "getting started"]
---

This page provides quick links to common documentation tasks. Use this as a starting point to find the information you need quickly.

## Getting started

<CardGroup cols={2}>
<Card title="Create your first page" icon="file-plus" href="/quickstart">
Set up your documentation and create your first page
</Card>
<Card title="Install the CLI" icon="terminal" href="/installation">

Check warning on line 15 in guides/common-tasks.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/common-tasks.mdx#L15

Use 'command-line tool' instead of 'CLI'.
Install the Mintlify CLI for local development
</Card>
<Card title="Choose a theme" icon="palette" href="/customize/themes">
Select and customize your documentation theme
</Card>
<Card title="Configure navigation" icon="sitemap" href="/organize/navigation">
Set up your documentation structure and navigation
</Card>
</CardGroup>

## Content creation

<CardGroup cols={2}>
<Card title="Format text" icon="text" href="/create/text">
Learn Markdown formatting, headers, and links
</Card>
<Card title="Add code blocks" icon="code" href="/create/code">
Display code with syntax highlighting and options
</Card>
<Card title="Use components" icon="puzzle-piece" href="/components/accordions">
Add interactive components like accordions and tabs
</Card>
<Card title="Add callouts" icon="message-exclamation" href="/components/callouts">
Highlight important information with callouts
</Card>
</CardGroup>

## Organization

<CardGroup cols={2}>
<Card title="Configure page metadata" icon="file-lines" href="/organize/pages">
Set titles, descriptions, and frontmatter
</Card>
<Card title="Organize with groups" icon="folder" href="/organize/navigation#groups">
Structure content with navigation groups
</Card>
<Card title="Add tabs" icon="window-restore" href="/organize/navigation#tabs">
Create separate documentation sections with tabs
</Card>
<Card title="Configure settings" icon="gear" href="/organize/settings">
Customize global documentation settings
</Card>
</CardGroup>

## API documentation

<CardGroup cols={2}>
<Card title="Set up OpenAPI" icon="square-terminal" href="/api-playground/openapi-setup">
Generate API docs from OpenAPI specifications
</Card>
<Card title="Create API pages" icon="code" href="/api-playground/overview">
Build interactive API playgrounds
</Card>
<Card title="Configure authentication" icon="lock" href="/api-playground/authentication">
Set up API authentication methods
</Card>
<Card title="Add MDX content" icon="file-code" href="/api-playground/mdx">
Enhance API pages with custom content
</Card>
</CardGroup>

## Customization

<CardGroup cols={2}>
<Card title="Customize colors" icon="palette" href="/organize/settings#param-colors">
Set your brand colors and theme
</Card>
<Card title="Add custom domain" icon="globe" href="/organize/settings#param-domain">
Configure a custom domain for your docs
</Card>
<Card title="Configure footer" icon="rectangle-vertical" href="/organize/settings#param-footer">
Customize footer links and content
</Card>
<Card title="Add analytics" icon="chart-line" href="/integrations/analytics/overview">
Track documentation usage with analytics
</Card>
</CardGroup>

## Deployment

<CardGroup cols={2}>
<Card title="Deploy with GitHub" icon="github" href="/deploy/github">
Connect GitHub for automated deployments
</Card>
<Card title="Set up CI checks" icon="gears" href="/deploy/ci">
Automate linting and validation in CI/CD
</Card>
<Card title="Preview changes" icon="eye" href="/deploy/github#install-the-github-app">
Generate preview deployments for pull requests
</Card>
<Card title="Configure custom domain" icon="link" href="/organize/settings#param-domain">
Set up a custom domain for your documentation
</Card>
</CardGroup>

## Optimization

<CardGroup cols={2}>
<Card title="Improve SEO" icon="magnifying-glass" href="/optimize/seo">
Optimize for search engines and social sharing
</Card>
<Card title="Add search keywords" icon="key" href="/organize/pages#internal-search-keywords">
Enhance page discoverability in search
</Card>
<Card title="Check broken links" icon="link-slash" href="/installation#find-broken-links">
Find and fix broken links in your docs
</Card>
<Card title="Configure redirects" icon="arrow-right-arrow-left" href="/organize/settings#param-redirects">
Set up URL redirects for moved content
</Card>
</CardGroup>

## Integrations

<CardGroup cols={2}>
<Card title="Add analytics" icon="chart-simple" href="/integrations/analytics/overview">
Integrate Google Analytics, Mixpanel, and more
</Card>
<Card title="Enable feedback" icon="comment" href="/organize/settings#param-feedback">
Collect user feedback on documentation pages
</Card>
<Card title="Configure search" icon="magnifying-glass" href="/organize/settings#param-search">
Customize search functionality
</Card>
<Card title="Add chat support" icon="messages" href="/organize/settings#param-chat">
Integrate chat support widgets
</Card>
</CardGroup>

## Troubleshooting

<CardGroup cols={2}>
<Card title="Fix deployment issues" icon="triangle-exclamation" href="/deploy/github#troubleshooting">
Resolve common GitHub deployment problems
</Card>
<Card title="Check broken links" icon="link-slash" href="/create/text#broken-links">
Use the CLI to find broken links

Check warning on line 152 in guides/common-tasks.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/common-tasks.mdx#L152

Use 'command-line tool' instead of 'CLI'.
</Card>
<Card title="Validate configuration" icon="check" href="/organize/settings">
Ensure your docs.json is properly configured
</Card>
<Card title="Debug navigation" icon="sitemap" href="/organize/navigation">
Fix navigation structure issues
</Card>
</CardGroup>

## Need more help?

<CardGroup cols={2}>
<Card title="Browse all guides" icon="book" href="/guides/improving-docs">
Explore comprehensive documentation guides
</Card>
<Card title="View all components" icon="puzzle-piece" href="/components/accordions">
See all available documentation components
</Card>
<Card title="Check settings reference" icon="gear" href="/organize/settings">
Review all configuration options
</Card>
<Card title="Contact support" icon="life-ring" href="https://mintlify.com/support">
Get help from the Mintlify team
</Card>
</CardGroup>
8 changes: 7 additions & 1 deletion organize/navigation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@

Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository.

<Card title="Learn more about pages" icon="file" href="/organize/pages">
Configure page metadata, titles, and frontmatter properties
</Card>

<img
className="block dark:hidden pointer-events-none"
src="/images/navigation/pages-light.png"
Expand Down Expand Up @@ -98,11 +102,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 105 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L105

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

Check warning on line 106 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L106

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L109

Use 'can't' instead of 'cannot'.

Check warning on line 109 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L109

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

```json
Expand Down Expand Up @@ -271,7 +275,7 @@
Use global anchors for external links that should appear on all pages, regardless of which section of your navigation the user is viewing. Global anchors are particularly useful for linking to resources outside your documentation, such as a blog, community forum, or support portal.

<Note>
Global anchors must include an `href` field pointing to an external URL. They cannot contain relative paths.

Check warning on line 278 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L278

Use 'can't' instead of 'cannot'.
</Note>

```json
Expand All @@ -298,7 +302,7 @@

## Dropdowns

Dropdowns are contained in 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 305 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L305

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

<img
className="block dark:hidden pointer-events-none"
Expand Down Expand Up @@ -413,15 +417,17 @@

Integrate OpenAPI specifications directly into your navigation structure to automatically generate API documentation. Create dedicated API sections or place endpoint pages within other navigation components.

Set a default OpenAPI specification at any level of your navigation hierarchy. Child elements will inherit this specification unless they define their own specification.

Check warning on line 420 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L420

Avoid using 'will'.

<Note>
When you add the `openapi` property to a navigation element (such as an anchor, tab, or group) without specifying any pages, Mintlify automatically generates pages for **all endpoints** defined in your OpenAPI specification.

Check warning on line 423 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L423

Use parentheses judiciously.

To control which endpoints appear, explicitly list the desired endpoints in a `pages` array.
</Note>

For more information about referencing OpenAPI endpoints in your docs, see the [OpenAPI setup](/api-playground/openapi-setup).
<Card title="Learn more about OpenAPI" icon="code" href="/api-playground/openapi-setup">
Set up OpenAPI specifications and generate API documentation
</Card>

```json
{
Expand Down Expand Up @@ -513,7 +519,7 @@

In the `navigation` object, `languages` is an array where each entry is an object that requires a `language` field and can contain any other navigation fields.

We currently support the following languages for localization:

Check warning on line 522 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L522

Try to avoid using first-person plural like 'We'.

<CardGroup cols={2}>
<Card title="Arabic (ar)" icon="/images/navigation/languages/ar.png" horizontal />
Expand Down Expand Up @@ -572,9 +578,9 @@

## Nesting

Navigation elements can be nested within each other to create complex hierarchies. You must have one root-level parent navigation element such as tabs, groups, or a dropdown. You can nest other types of navigation elements within your primary navigation pattern.

Check warning on line 581 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L581

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

Each navigation element can contain one type of child element at each level of your navigation hierarchy. For example, a tab can contain anchors that contain groups, but a tab cannot contain both anchors and groups at the same level.

Check warning on line 583 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L583

Use 'can't' instead of 'cannot'.

<CodeGroup>

Expand Down Expand Up @@ -796,7 +802,7 @@

## 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 are enabled for your site using the `styling` property in your `docs.json`.

Check warning on line 805 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L805

Use 'don't' instead of 'do not'.

Check warning on line 805 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L805

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

<CodeGroup>

Expand All @@ -820,10 +826,10 @@

### Enable auto-navigation for groups

When a user expands a navigation group, some themes will automatically navigate to the first page in the group. You can override a theme's default behavior using the `drilldown` option.

Check warning on line 829 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L829

Avoid using 'will'.

- Set to `true` to force automatic navigation to the first page when a navigation group is selected.

Check warning on line 831 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L831

In general, use active voice instead of passive voice ('is selected').
- Set to `false` to prevent navigation and only expand or collapse the group when it is selected.

Check warning on line 832 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L832

Use 'it's' instead of 'it is'.

Check warning on line 832 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L832

In general, use active voice instead of passive voice ('is selected').
- Leave unset to use the theme's default behavior.

<CodeGroup>
Expand Down
12 changes: 10 additions & 2 deletions organize/pages.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
keywords: ["tags", "tag", "frontmatter", "metadata", "layout"]
---

Each page is a Markdown file. Both `.mdx` and `.md` file types are supported. We recommend using MDX, which combines Markdown with React components to create rich, interactive documentation. Plain Markdown (`.md`) is supported for easier migration from other platforms, but should be updated to MDX for full functionality.

Check warning on line 7 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L7

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

Check warning on line 7 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L7

Try to avoid using first-person plural like 'We'.

Check warning on line 7 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L7

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

Check warning on line 7 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L7

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

Check warning on line 7 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L7

Use 'capability' or 'feature' instead of 'functionality'.

## Page metadata

Expand All @@ -15,15 +15,19 @@
- Page titles and descriptions
- Sidebar titles, icons, and tags
- Page layouts
- SEO meta tags

Check warning on line 18 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L18

Spell out 'SEO', if it's unfamiliar to the audience.
- Custom metadata

<Card title="Learn more about navigation" icon="sitemap" href="/organize/navigation">
Design information architecture and configure navigation structure
</Card>

<ResponseField name="title" type="string" required>
The title of your page that appears in navigation and browser tabs.
</ResponseField>

<ResponseField name="description" type="string">
A brief description of what this page covers. Appears under the title and improves SEO.

Check warning on line 30 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L30

Spell out 'SEO', if it's unfamiliar to the audience.
</ResponseField>

<ResponseField name="sidebarTitle" type="string">
Expand Down Expand Up @@ -70,7 +74,7 @@

### Default

If no mode is defined, defaults to a standard layout with a sidebar navigation and table of contents.

Check warning on line 77 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L77

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

```yaml
---
Expand All @@ -80,7 +84,7 @@

### Wide

Wide mode hides the table of contents. This is useful for pages that do not have any headings or if you prefer to use the extra horizontal space. Wide mode is available for all themes.

Check warning on line 87 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L87

Use 'don't' instead of 'do not'.

```yaml
---
Expand Down Expand Up @@ -132,7 +136,9 @@
---
```

Learn more about building [API documentation](/api-playground/overview).
<Card title="Learn more about API documentation" icon="square-terminal" href="/api-playground/overview">
Build interactive API playgrounds and reference documentation
</Card>

## External links

Expand All @@ -147,10 +153,10 @@

## Search engine optimization

Most SEO meta tags are automatically generated. You can set SEO meta tags manually to improve your site's SEO, social sharing, and browser compatibility.

Check warning on line 156 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L156

Spell out 'SEO', if it's unfamiliar to the audience.

Check warning on line 156 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L156

Spell out 'SEO', if it's unfamiliar to the audience.

Check warning on line 156 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L156

Spell out 'SEO', if it's unfamiliar to the audience.

<Note>
Meta tags with colons must be wrapped in quotes.

Check warning on line 159 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L159

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

```yaml
Expand All @@ -159,11 +165,13 @@
---
```

See [SEO](/optimize/seo) for complete SEO metadata options.
<Card title="Learn more about SEO" icon="magnifying-glass" href="/optimize/seo">
Optimize your documentation for search engines and social sharing
</Card>

## Internal search keywords

Enhance a specific page's discoverability in the built-in search by providing `keywords` in your metadata. These keywords won't appear as part of the page content or in search results, but users that search for them will be shown the page as a result.

Check warning on line 174 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L174

Avoid using 'will'.

Check warning on line 174 in organize/pages.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/pages.mdx#L174

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

```yaml
---
Expand Down
Loading