Installation

npm i -g mintlify

Requires Node 20.17 or higher. LTS versions recommended. Node 25+ is not supported.

Local preview

mintlify dev

Run at the root of your Mintlify project to preview changes locally. Opens in the browser by default.

mintlify dev

Options

| Flag | Description | Default | |------|-------------|---------| | --port <number> | Port to run the preview on | 3000 | | --no-open | Skip opening the preview in the browser | — | | --groups <group...> | Mock user groups for local testing | — | | --disable-openapi | Disable OpenAPI file generation | — |

Custom port

mintlify dev --port 3333

If the specified port is already in use, the CLI automatically tries the next available port.

Troubleshooting

If mintlify dev is not working, try these steps in order:

1. Make sure you are running in a folder with a docs.json file.
2. Run mintlify update to get the latest version of the CLI.
3. Make sure you are using Node 20.17 or higher.
4. Delete the contents of the .mintlify folder in your home directory.

Validate and check

mintlify validate

Validate the documentation build in strict mode. Exits with a non-zero code on any warning or error — useful in CI.

mintlify validate

Options

| Flag | Description | |------|-------------| | --groups <group...> | Mock user groups for validation | | --disable-openapi | Disable OpenAPI file generation |

mintlify broken-links

Check for broken internal links in your project.

mintlify broken-links

Options

| Flag | Description | |------|-------------| | --check-anchors | Also validate anchor links like link-path#section against heading slugs | | --check-external | Also check external links for broken URLs | | --check-snippets | Also check links inside <Snippet> components |

mintlify openapi-check <filename>

Check an OpenAPI spec for errors. Accepts a local file path or a URL.

mintlify openapi-check ./openapi.yaml
mintlify openapi-check https://petstore3.swagger.io/api/v3/openapi.json

mintlify a11y

Check for accessibility issues in your documentation. Also available as mintlify accessibility, mintlify accessibility-check, and mintlify a11y-check.

mintlify a11y

Options

| Flag | Description | |------|-------------| | --skip-contrast | Skip color contrast checks | | --skip-alt-text | Skip alt text checks on images and videos |

Create and manage content

mintlify new [directory]

Create a new Mintlify documentation site. Defaults to the current directory.

mintlify new
mintlify new my-docs

Options

| Flag | Description | |------|-------------| | --theme <name> | Theme for the documentation site | | --name <name> | Name of the documentation project | | --force | Initialize in a non-empty directory |

mintlify rename <from> <to>

Rename a file and update all internal references to it throughout the project.

mintlify rename introduction.mdx overview.mdx

Options

| Flag | Description | |------|-------------| | --force | Rename files and skip errors |

mintlify scrape <url>

Scrape an entire documentation site and convert it to Mintlify MDX files. Also available as mintlify scrape site <url>.

mintlify scrape https://example.com/docs

Options

| Flag | Description | |------|-------------| | --filter <path> | Only scrape URLs matching this path (e.g. /docs matches /docs and /docs/*) |

mintlify scrape page <url>

Scrape a single documentation page and convert it to an MDX file.

mintlify scrape page https://example.com/docs/introduction

mintlify scrape openapi <location>

Generate MDX files from an OpenAPI spec. Accepts a local file path or a URL.

mintlify scrape openapi ./openapi.yaml
mintlify scrape openapi https://petstore3.swagger.io/api/v3/openapi.json

Options

| Flag | Description | Default | |------|-------------|---------| | --outDir <path> | Folder to write the generated files | — | | --overwrite | Overwrite existing files | false |

mintlify migrate-mdx

Migrate MDX OpenAPI endpoint pages to x-mint extensions and docs.json.

mintlify upgrade

Upgrade mint.json to docs.json. Creates a docs.json from your existing mint.json.

mintlify workflow

Add a workflow to your documentation repository.

Export

mintlify export

Export a static site as a zip file for air-gapped deployment.

mintlify export
mintlify export --output docs.zip

Options

| Flag | Description | Default | |------|-------------|---------| | --output <path> | Output zip file path | export.zip | | --groups <group...> | Mock user groups for export | — | | --disable-openapi | Disable OpenAPI file generation | — |

CLI management

mintlify update

Update the CLI to the latest version.

mintlify version

Display the current version of the CLI and client. Also available as mintlify v.

Get Started

Create an account to start using Mintlify for your documentation.