
Installing the CLI
Prerequisite: Please install Node.js before proceeding.
1
Install the CLI.
Run the following command to install the CLI:
2
Preview locally.
Navigate to your docs directory (where your A local preview of your documentation will be available at
docs.json
file is located) and execute the following command:http://localhost:3000
.Updates
If your local preview is out of sync with what you see on the web in the production version, update your local CLI:mint update
command is not available on your local version, re-install the CLI with the latest version:
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:
Previewing as a specific group
If you use partial authentication to restrict access to your documentation, you can preview as a specific authentication group by using the--group [groupname]
flag.
For example, if you have a group named admin
, you can preview as a member of that group with the command:
Additional commands
Find broken links
Identify any broken internal links with the following command:Find accessibility issues
Test the color contrast ratios and search for missing alt text on images and videos in your documentation with the following command:Check OpenAPI spec
Check your OpenAPI file for errors with the following command:./openapi.yaml
) or a URL (for example, https://petstore3.swagger.io/api/v3/openapi.json
).
Rename files
Rename and update all references to files with the following command:Migrate MDX endpoint pages
Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command:docs.json
, moves MDX content to the x-mint
extension in your OpenAPI specification, and updates your navigation. See Migrating from MDX for detailed information.
Formatting
While developing locally, we recommend using extensions in your IDE to recognize and formatMDX
files.
If you use Cursor, Windsurf, or VS Code, we recommend the MDX VS Code extension for syntax highlighting, and Prettier for code formatting.
If you use JetBrains, we recommend the MDX IntelliJ IDEA plugin for syntax highlighting, and setting up Prettier for code formatting.
Troubleshooting
Error: Could not load the "sharp" module using the darwin-arm64 runtime
Error: Could not load the "sharp" module using the darwin-arm64 runtime
This may be due to an outdated version of node. Try the following:
- Remove the currently-installed version of the mint CLI:
npm uninstall -g mint
- Upgrade to Node.js.
- Reinstall the mint CLI:
npm install -g mint
Issue: Encountering an unknown error
Issue: Encountering an unknown error
Solution: Go to the root of your device and delete the
~/.mintlify
folder. Afterwards, run mint dev
again.Error: permission denied
Error: permission denied
This is due to not having the required permissions to globally install node packages.Solution: Try running
sudo npm i -g mint
. You will be prompted for your password, which is the one you use to unlock your computer.The local preview doesn't look the same as my docs do on the web
The local preview doesn't look the same as my docs do on the web
This is likely due to an outdated version of the CLI.Solution: Run
mint update
to get the latest changes.mintlify vs. mint package
mintlify vs. mint package
If you have any problems with the CLI package, you should first run
npm ls -g
. This command shows what packages are globally installed on your machine.If you don’t use npm or don’t see it in the -g list, try which mint
to locate the installation.If you have a package named mint
and a package named mintlify
installed, you should uninstall mintlify
.- Uninstall the old package:
- Clear your npm cache:
- Reinstall the new package: