Skip to main content

​
Prerequisites

  • The Mintlify CLI installed globally, or run commands with npx mint.

​
Start the local preview

Navigate to your documentation directory and run:
The local preview starts at http://localhost:3000. As you edit, changes appear in real time. By default, the preview opens automatically in your browser. To prevent the browser from opening, use the --no-open flag:
To generate a preview without installing the CLI globally, run:

​
Preview a directory without a docs.json file

If you run mint dev in a directory that has no docs.json file, the CLI generates a docs.json file from your directory structure. The generated navigation follows these patterns:
  • Creates a group named Introduction for Markdown and MDX files at the root of the directory.
  • Creates a group for each top-level subdirectory, and nested subdirectories become subgroups.
  • Pages named index or readme appear first in their group. Other pages and folders sort alphabetically, or numerically if the titles contain numbers.
  • Group names use subdirectory names, without any leading number prefix. For example, a folder named 01-getting-started becomes a group named Getting started.
  • The CLI skips files and folders that start with . or _, node_modules and snippets folders, and paths in your .mintignore file.
The site name comes from the name field in a package.json file in the directory or its parent directory. If there is no package.json file, the CLI uses the directory name. Edit the generated docs.json file to customize your navigation, theme, and colors.
If you write in VS Code or Cursor, the Mintlify MDX extension runs this preview in a panel beside your editor and scrolls it to match the page you are editing.

​
Sign in for search and assistant

You must authenticate the CLI with your Mintlify account to enable search and the assistant.
After you authenticate with the mint login command, the CLI stores your credentials in ~/.config/mintlify/config.json so you stay signed in across sessions. The CLI also prompts you to select a default project. Once signed in, run mint dev to start the local preview with search and the assistant enabled. The assistant uses the same indexed content as your deployed documentation site. To check your authentication status, run:
To log out, run:

​
Custom ports

By default, the CLI uses port 3000. To use a different port, use the --port flag:
If the port is already in use, the CLI automatically tries the next available port.

​
Preview on other devices

By default, the local preview only accepts connections from your own computer at localhost. To open the preview on a phone or another computer on your network, use the --host flag:
The CLI then prints a network URL that other devices on the same network can open.

​
Skip OpenAPI processing

If you have many OpenAPI files, skip OpenAPI processing during local development to improve performance with the --disable-openapi flag:

​
Disable navigation prefetching

By default, the local preview prefetches nearby pages to optimize page load speeds. For very large sites, this can slow down the page you are actively viewing if many pages compile in the background at the same time. If you have thousands of pages and notice slow page loads during local preview, disable prefetching with the --disable-prefetch flag:
With prefetching disabled, pages compile only when you navigate to them. Individual page loads take longer than a prefetched page, but the page you request is not competing with background compilation.

​
Preview as a specific group

If you use group-based access control, preview as a specific authentication group with the --groups flag:
By default, the local preview shows content as a signed-out reader. To check <Visibility for="signed-in"> content, use the --signed-in flag to preview as a signed-in reader with no groups. The --groups flag also previews as a signed-in reader.
See Authentication setup for more information on groups.