From 639d442048efa57fefab7131473d44a5b2945587 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 4 Nov 2025 20:35:10 +0000
Subject: [PATCH] Update installation.mdx
---
installation.mdx | 155 +++++++----------------------------------------
1 file changed, 21 insertions(+), 134 deletions(-)
diff --git a/installation.mdx b/installation.mdx
index 29dbcbb96..bb5c96b93 100644
--- a/installation.mdx
+++ b/installation.mdx
@@ -14,9 +14,7 @@ description: "Use the CLI to preview and maintain your documentation locally"
alt="Decorative graphic representing the CLI."
/>
-Use the CLI to preview your documentation locally as you write and edit. View changes in real-time before deploying, test your documentation site's appearance and functionality, and catch issues like broken links or accessibility problems.
-
-The CLI also has utilities for maintaining your documentation, including commands to rename files, validate OpenAPI specifications, and migrate content between formats.
+Use the CLI to preview your documentation locally as you write and edit.
## Install the CLI
@@ -24,200 +22,89 @@ The CLI also has utilities for maintaining your documentation, including command
**Prerequisite**: The CLI requires [Node.js](https://nodejs.org/en) v19 or higher.
-Run the following command to install the [CLI](https://www.npmjs.com/package/mint):
-
-
- ```bash npm
- npm i -g mint
- ```
+
+ ```bash npm
+ npm i -g mint
+ ```
- ```bash pnpm
- pnpm add -g mint
- ```
-
+ ```bash pnpm
+ pnpm add -g mint
+ ```
+
## Preview locally
-To generate a local preview, navigate to your documentation directory (where your `docs.json` file is located) and run the following command:
+Navigate to your documentation directory and run:
```bash
mint dev
```
-A local preview of your documentation is available at `http://localhost:3000`.
-
-Alternatively, if you do not want to install the CLI globally, you can run a one-time script:
-
-```bash
-npx mint dev
-```
+Your documentation is available at `http://localhost:3000`.
### 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:
+Use the `--port` flag to customize the port:
```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.
-```
-
### Preview 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 `--groups [groupname]` flag.
-
-For example, if you have a group named `admin`, you can preview as a member of that group with the command:
+If you use partial authentication, preview as a specific group:
```bash
mint dev --groups admin
```
-## Create a new project
-
-To create a new documentation project, run the following command:
-
-```bash
-mint new [directory]
-```
-
-This command clones the [starter kit](https://github.com/mintlify/starter) into a specified directory. If no directory is specified, the CLI tool prompts you to create a new subdirectory or overwrite the current directory.
-
-
- If you overwrite the current directory, any existing files in the directory will be deleted.
-
-
-The CLI tool prompts you for a project name and [theme](/customize/themes) to finish setting up your project.
-
-You can run `mint new` with the following flags:
-
-* `--theme`: Set the theme of the new project.
-* `--name`: Set the name of the new project.
-* `--force`: Overwrite the current directory if it already exists.
-
-For example, to create a new project in the `docs` directory with the name `my-project` and the theme `linden`, run the following command:
-
-```bash
-mint new docs --name my-project --theme linden
-```
-## Update the CLI
+## Additional commands
-If your local preview is out of sync with what you see on the web in the production version, update your local CLI:
+### Update the 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
- npm i -g mint@latest
- ```
-
- ```bash pnpm
- pnpm add -g mint@latest
- ```
-
-
-## Additional commands
-
### Find broken links
-Identify any broken internal links with the following command:
-
```bash
mint broken-links
```
### 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:
-
```bash
mint a11y
```
### Check OpenAPI spec
-Check your OpenAPI file for errors with the following command:
-
```bash
mint openapi-check
```
-Pass a filename (for example, `./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:
-
```bash
mint rename
```
-### Migrate MDX endpoint pages
-
-Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command:
-
-```bash
-mint migrate-mdx
-```
-
-This command converts individual MDX endpoint pages to autogenerated pages defined in your `docs.json`, moves MDX content to the `x-mint` extension in your OpenAPI specification, and updates your navigation. See [Migrating from MDX](/guides/migrating-from-mdx) for detailed information.
-
-## Formatting
-
-While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files.
-
-If you use Cursor, Windsurf, or VS Code, we recommend the [MDX VS Code 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
- 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`
+ 1. Remove the CLI: `npm uninstall -g mint`
+ 2. Upgrade to Node.js v19+
+ 3. Reinstall: `npm install -g mint`
- **Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again.
+ Delete the `~/.mintlify` folder and run `mint dev` again.
- 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.
+ Run `sudo npm i -g mint` and enter your password.
- This is likely due to an outdated version of the CLI.
-
- **Solution:** Run `mint update` to get the latest changes.
-
-
- 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`.
-
- 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 i -g mint
- ```
+ Run `mint update` to get the latest changes.