mintlify

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.