mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Kathryn Isabelle Lawrence
e0e665074f
* update cli docs * remove CodeGroup tags * format troubleshooting steps --------- Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
157 lines
4.8 KiB
Plaintext
157 lines
4.8 KiB
Plaintext
---
|
|
title: "CLI installation"
|
|
sidebarTitle: "Installation"
|
|
description: "Install the CLI to preview and develop your docs locally"
|
|
icon: "terminal"
|
|
---
|
|
|
|
<img
|
|
className="block dark:hidden my-0 pointer-events-none"
|
|
src="/images/installation/local-development-light.png"
|
|
/>
|
|
<img
|
|
className="hidden dark:block my-0 pointer-events-none"
|
|
src="/images/installation/local-development-dark.png"
|
|
/>
|
|
|
|
## Installing the CLI
|
|
|
|
<Info>
|
|
**Prerequisite**: Please install [Node.js](https://nodejs.org/en) before proceeding.
|
|
</Info>
|
|
|
|
<Steps>
|
|
<Step title="Install the CLI.">
|
|
Run the following command to install the [CLI](https://www.npmjs.com/package/mint):
|
|
|
|
```bash
|
|
npm i -g mint
|
|
```
|
|
|
|
</Step>
|
|
<Step title="Preview locally.">
|
|
Navigate to your docs directory (where your `docs.json` file is located) and execute the following command:
|
|
|
|
```bash
|
|
mint dev
|
|
```
|
|
|
|
A local preview of your documentation will be available at `http://localhost:3000`.
|
|
</Step>
|
|
</Steps>
|
|
|
|
Alternatively, if you do not want to install the CLI globally, you can run a one-time script:
|
|
|
|
```bash
|
|
npx mint dev
|
|
```
|
|
|
|
## Updates
|
|
|
|
If your local preview is out of sync with what you see on the web in the production version, update your local CLI:
|
|
|
|
```bash
|
|
mint update
|
|
```
|
|
|
|
If this `mint update` command is not available on your local version, re-install the CLI with the latest version:
|
|
|
|
```bash
|
|
npm i -g mint@latest
|
|
```
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
mint dev --port 3333
|
|
```
|
|
|
|
If you attempt to run on a port that is already in use, it will use the next available port:
|
|
|
|
```mdx
|
|
Port 3000 is already in use. Trying 3001 instead.
|
|
```
|
|
|
|
## Additional commands
|
|
|
|
While `mint dev` is the most commonly used command, there are other commands you can use to manage your documentation.
|
|
|
|
### Finding broken links
|
|
|
|
The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
|
|
|
|
```bash
|
|
mint broken-links
|
|
```
|
|
|
|
### Checking OpenAPI spec
|
|
|
|
You can use the CLI to check your OpenAPI file for errors using the following command:
|
|
|
|
```bash
|
|
mint openapi-check <openapiFilenameOrUrl>
|
|
```
|
|
|
|
You can pass in a filename (e.g. `./openapi.yaml`) or a URL (e.g. `https://petstore3.swagger.io/api/v3/openapi.json`).
|
|
|
|
### Renaming files
|
|
|
|
You can rename and update all references to files using the following command:
|
|
|
|
```bash
|
|
mint rename <oldFilename> <newFilename>
|
|
```
|
|
|
|
## Formatting
|
|
|
|
While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files.
|
|
|
|
If you use Cursor, Windsurf, or VSCode, we recommend the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
|
|
|
|
If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) for syntax highlighting, and setting up [Prettier](https://prettier.io/docs/webstorm) for code formatting.
|
|
|
|
## Troubleshooting
|
|
|
|
<AccordionGroup>
|
|
<Accordion title='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:
|
|
|
|
1. Remove the currently-installed version of the mint CLI: `npm uninstall -g mint`
|
|
2. Upgrade to Node.js.
|
|
3. Reinstall the mint CLI: `npm install -g mint`
|
|
</Accordion>
|
|
<Accordion title="Issue: Encountering an unknown error">
|
|
**Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again.
|
|
</Accordion>
|
|
<Accordion title="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.
|
|
</Accordion>
|
|
<Accordion title="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.
|
|
</Accordion>
|
|
<Accordion title="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 have a package named `mint` and a package named `mintlify` installed, you should uninstall `mintlify`.
|
|
|
|
1. Uninstall the old package:
|
|
```bash
|
|
npm uninstall -g mintlify
|
|
```
|
|
2. Clear your npm cache:
|
|
```bash
|
|
npm cache clean --force
|
|
```
|
|
3. Reinstall the new package:
|
|
```bash
|
|
npm install -g mint
|
|
```
|
|
</Accordion>
|
|
</AccordionGroup>
|