Skip to main content
This guide is for documentation contributors who want to preview W&B Weave documentation changes locally before they’re published. By running the Mintlify CLI on your machine, you can verify your edits render correctly, catch broken links, and iterate quickly without waiting for a deployment.
Prerequisite: Install Node.js (version 19 or higher) before proceeding.
Upgrade to docs.json before proceeding and delete the legacy mint.json file.

​
Install and run Mintlify

Follow these steps to install and run Mintlify on your operating system:
  1. Install Mintlify: 
    npm i -g mintlify
  2. Navigate to the docs directory (where the docs.json file is located) and start the local preview server: 
    mintlify dev
A local preview of your documentation is available at http://localhost:3000. You now have a running local environment that mirrors the published Weave docs site.

​
Custom ports

By default, Mintlify uses port 3000. If port 3000 is already in use on your machine or you prefer to run multiple previews at once, use the --port flag to change the port Mintlify listens on. For example, to run Mintlify on port 3333, use this command: 
mintlify dev --port 3333
If you attempt to run Mintlify on a port that’s already in use, it uses the next available port: 
Port 3000 is already in use. Trying 3001 instead.

​
Mintlify versions

Keep your CLI in sync with the production Mintlify version so your local preview matches what readers see on the published site. Each CLI release is associated with a specific version of Mintlify. If your local website doesn’t align with the production version, update the CLI: 
npm i -g mintlify@latest
Broken links degrade the reader experience, so check your changes for broken references before you open a pull request. The CLI can validate reference links in your documentation. To identify broken links, run mintlify broken-links: 
mintlify broken-links

​
Deployment

Unlimited editors available under the Pro Plan and above.
If the deployment is successful, you should see a confirmation message indicating that all checks have passed.

​
Code formatting

Consistent MDX formatting makes your changes easier to review and reduces accidental syntax errors. Use extensions in your IDE to recognize and format MDX. If you’re a VSCode user, consider the MDX VSCode extension for syntax highlighting, and Prettier for code formatting.

​
Troubleshooting

The following sections describe common issues you may encounter when you run the Mintlify CLI locally, along with their resolutions.
This may be due to an outdated version of Node.js. Try the following:
  1. Remove the installed version of mintlify: npm remove -g mintlify.
  2. Upgrade to Node.js v19 or higher.
  3. Reinstall mintlify: npm install -g mintlify.
Solution: Go to the root of your device and delete the ~/.mintlify folder. Afterward, run mintlify dev again.
Curious about what changed in the CLI version? For more information, see the CLI changelog.