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
9 changes: 9 additions & 0 deletions ai/assistant.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,15 @@
- Add [hidden pages](/organize/hidden-pages) with additional context that users don't need, but the assistant can reference.
</Card>

## Use the assistant in local preview

The assistant is available in your local preview when you are logged in to the CLI. This lets you test assistant behavior, custom instructions, and responses while developing documentation locally.

Check warning on line 203 in ai/assistant.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/assistant.mdx#L203

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

1. Run `mint login` to authenticate.
2. Run `mint dev` to start the local preview.

The assistant in local preview uses the same indexed content as your deployed documentation site.

## Use the assistant

Users have multiple ways to start a conversation with the assistant. Each method opens a chat panel on the right side of your docs. Users can ask any question and the assistant searches your documentation for an answer. If the assistant cannot retrieve relevant information, the assistant responds that it cannot answer the question.
Expand Down
43 changes: 2 additions & 41 deletions guides/migrating-from-mdx.mdx
Original file line number Diff line number Diff line change
@@ -1,54 +1,15 @@
---
title: "Migrating MDX API pages to OpenAPI navigation"
sidebarTitle: "Migrate from MDX to OAS"

Check warning on line 3 in guides/migrating-from-mdx.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/migrating-from-mdx.mdx#L3

Spell out 'OAS', if it's unfamiliar to the audience.
description: "Migrate your manually written MDX API pages to automated OpenAPI-generated documentation with flexible navigation and endpoint grouping."
keywords: ["API migration", "mint migrate-mdx", "OpenAPI migration", "x-mint extension"]
keywords: ["API migration", "OpenAPI migration", "x-mint extension"]
---

If you are currently using individual MDX pages for your API endpoints, you can migrate to autogenerating pages from your OpenAPI specification while retaining the customizability of individual pages. This can help you reduce the number of files you need to maintain and improve the consistency of your API documentation.

You can define metadata and content for each endpoint in your OpenAPI specification and organize endpoints where you want them in your navigation.

## CLI migration

The `mint migrate-mdx` command is the recommended way to migrate from MDX endpoint pages to autogenerated pages.

This command:
- Parses your `docs.json` navigation structure.
- Identifies MDX pages that generate OpenAPI endpoint pages.
- Extracts content from MDX files and moves it to the `x-mint` extension in your OpenAPI specification.
- Updates your `docs.json` to reference the OpenAPI endpoints directly instead of MDX files.
- Deletes the original MDX endpoint files.

<Info>
If you already have `x-mint` defined for an endpoint and also have an MDX page with content for that endpoint, the MDX content overwrites existing `x-mint` settings.

If you have multiple MDX pages for the same endpoint with different content, the script uses the content from the page that appears last in your `docs.json`.

The migration tool does not support previewing changes before applying them.
</Info>

<Steps>
<Step title="Prepare your OpenAPI specification.">
Ensure your OpenAPI specification is valid and includes all endpoints you want to document.

Any MDX pages you want to migrate must have the `openapi:` frontmatter referencing an endpoint.

<Tip>
Validate your OpenAPI file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint).
</Tip>
</Step>
<Step title="Install the Mint CLI">
If needed, install or update the [Mint CLI](/installation).
</Step>
<Step title="Run the migration command.">
```bash
mint migrate-mdx
```
</Step>
</Steps>

## Manual migration steps
## Migration steps

<Steps>
<Step title="Prepare your OpenAPI specification.">
Expand Down
118 changes: 64 additions & 54 deletions installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,28 @@
```
</CodeGroup>

## Log in

Log in to your Mintlify account to unlock features in local preview, including the AI assistant and search. Run:

```bash
mint login
```

This opens your browser to authenticate. After logging in, your session persists across CLI commands.

To check your current authentication status:

```bash
mint status
```

To log out:

```bash
mint logout
```

## Preview locally

Navigate to your documentation directory containing your `docs.json` file and run:
Expand All @@ -95,6 +117,8 @@
npx mint dev
```

When you are logged in, the local preview includes the AI assistant and search — the same features available on your deployed documentation site. See [Assistant](/ai/assistant) for more information.

Check warning on line 120 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L120

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

Check warning on line 120 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L120

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

### Custom ports

By default, the CLI uses port 3000. You can customize the port using the `--port` flag. To run the CLI on port 3333, for instance, use this command:
Expand Down Expand Up @@ -230,22 +254,14 @@

### Check OpenAPI spec

Check your OpenAPI file for errors with the following command:

```bash
mint openapi-check <OpenAPI filename or URL>
```

Pass a filename (for example, `./openapi.yaml`) or a URL (for example, `https://petstore3.swagger.io/api/v3/openapi.json`).

To check a locally hosted OpenAPI file served over HTTP, use the `--local-schema` flag:
OpenAPI validation is built into the `mint validate` command. When you run `mint validate`, your OpenAPI specifications are automatically checked for errors alongside other documentation checks.

Check warning on line 257 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L257

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

```bash
mint openapi-check http://localhost:8080/openapi.json --local-schema
mint validate
```

<Note>
Production deployments only support HTTPS URLs. The `--local-schema` flag is for local development only.
The standalone `mint openapi-check` command is deprecated. Use `mint validate` instead, which includes OpenAPI validation along with other documentation checks.

Check warning on line 264 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L264

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

### Create a workflow
Expand All @@ -258,79 +274,73 @@

The CLI prompts you for a name, trigger type, and other settings, then creates a `.md` file in `.mintlify/workflows/`.

### Rename files

Rename and update all references to files with the following command:

```bash
mint rename <path/to/old-filename> <path/to/new-filename>
```
### View analytics

Use `--force` to rename files and skip errors:
View analytics for your documentation site directly from the CLI. You must be [logged in](#log-in) to use analytics commands.

```bash
mint rename <path/to/old-filename> <path/to/new-filename> --force
mint analytics stats
```

### Migrate MDX endpoint pages

Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command:
This shows key metrics including views, visitors, searches, feedback, and assistant usage for the last 7 days by default.

```bash
mint migrate-mdx
```
Available subcommands:

Check warning on line 287 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L287

Did you really mean 'subcommands'?

This command converts individual MDX endpoint pages to autogenerated pages defined in your `docs.json`, moves MDX content to the `x-mint` extension in your OpenAPI specification, and updates your navigation. See [Migrating from MDX](/guides/migrating-from-mdx) for detailed information.
| Subcommand | Description |

Check warning on line 289 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L289

Did you really mean 'Subcommand'?
| --- | --- |
| `mint analytics stats` | Display KPI numbers (views, visitors, searches, assistant usage). |

Check warning on line 291 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L291

Spell out 'KPI', if it's unfamiliar to the audience.
| `mint analytics search` | Display search query analytics. |
| `mint analytics feedback` | Display feedback analytics. |
| `mint analytics conversation list` | List assistant conversations. |
| `mint analytics conversation view <id>` | View a single assistant conversation. |

### Export for offline viewing
Common flags:

Export your entire documentation site as a self-contained zip archive for offline viewing and distribution:
| Flag | Description |
| --- | --- |
| `--from` | Start date in `YYYY-MM-DD` format (defaults to 7 days ago). |
| `--to` | End date in `YYYY-MM-DD` format (defaults to today). |
| `--subdomain` | Documentation subdomain (defaults to the configured value). |
| `--format` | Output format: `table`, `plain`, `json`, or `graph`. |

```bash
mint export
```
### Manage configuration

Use `--output` to set a custom filename, `--groups` to include pages restricted by [user groups](/deploy/authentication-setup#control-access-with-groups), and `--disable-openapi` to skip OpenAPI processing.
Set default values for CLI commands such as your subdomain and date ranges:

```bash
mint export --output customer-docs.zip --groups enterprise
mint config set subdomain your-subdomain
```

See [Offline export](/deploy/export) for details on all options and distributing the exported archive.

### Import content
Available configuration keys:

Scrape content from an external documentation site or OpenAPI specification using the `mint scrape` commands. This is useful when you migrate your documentation from another platform to Mintlify.
| Key | Description |
| --- | --- |
| `subdomain` | Default documentation subdomain for analytics and other commands. |
| `dateFrom` | Default start date for analytics queries. |
| `dateTo` | Default end date for analytics queries. |

**Import an entire site:**
To view or clear a configuration value:

```bash
mint scrape <url>
mint config get subdomain
mint config clear subdomain
```

Use the `--filter` (or `-f`) flag to limit scraping to URLs matching a specific path prefix:

```bash
mint scrape <url> --filter=<path>
```
### Export for offline viewing

**Import a single page:**
Export your entire documentation site as a self-contained zip archive for offline viewing and distribution:

```bash
mint scrape page <url>
mint export
```

**Generate pages from an OpenAPI spec:**
Use `--output` to set a custom filename, `--groups` to include pages restricted by [user groups](/deploy/authentication-setup#control-access-with-groups), and `--disable-openapi` to skip OpenAPI processing.

```bash
mint scrape openapi <openApiFilename or URL>
mint export --output customer-docs.zip --groups enterprise
```

| Flag | Description |
| --- | --- |
| `--outDir` | Directory to write generated files. Defaults to `./docs`. |
| `--overwrite` | Overwrite existing files. |
| `--no-writeFiles` | Preview output without writing files. |
See [Offline export](/deploy/export) for details on all options and distributing the exported archive.

### Upgrade configuration

Expand All @@ -340,7 +350,7 @@
mint upgrade
```

See [Global settings](/organize/settings) for more information about `docs.json`.

Check warning on line 353 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L353

Did you really mean 'informat'?

### Check version

Expand Down
12 changes: 1 addition & 11 deletions migration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -170,17 +170,7 @@ To migrate your content to Mintlify, you need:

1. If your content is already in Markdown format, copy the content to your Mintlify project. Otherwise, convert your content to MDX format.
2. Create your `docs.json` referencing the paths to your Markdown pages.
3. If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground. You can also generate MDX pages from your spec using the `mint scrape openapi` command:

```bash
mint scrape openapi <openApiFilename or URL>
```

| Flag | Description |
| --- | --- |
| `--outDir` | Directory to write generated files. Defaults to `./docs`. |
| `--overwrite` | Overwrite existing files. |
| `--no-writeFiles` | Preview output without writing files. |
3. If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground. See [OpenAPI setup](/api-playground/openapi-setup) for more information on configuring your API documentation.

<Tip>
If you migrate your content as `.md` files, convert them to `.mdx` to support interactive features like React components.
Expand Down
Loading