From 1737b4b18827d9c7a396287b8385dd8736f62757 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 05:57:03 +0000 Subject: [PATCH 1/8] Update installation.mdx --- installation.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/installation.mdx b/installation.mdx index e17fb6a11..9e70ef3cb 100644 --- a/installation.mdx +++ b/installation.mdx @@ -1,6 +1,6 @@ --- title: "CLI installation" -description: "Use the CLI to preview docs locally, test changes in real-time, and catch issues before deploying your documentation site." +description: "Install the CLI to preview docs locally and maintain your documentation." keywords: ["CLI", "npm", "local development", "Node.js"] --- @@ -15,9 +15,7 @@ keywords: ["CLI", "npm", "local development", "Node.js"] 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. +Preview your documentation locally, test changes in real-time, and use utilities to maintain your docs. ## Install the CLI From dd04d5d88940d05bfdfcf402f7a73bcb25f9adfa Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 05:57:09 +0000 Subject: [PATCH 2/8] Update installation.mdx --- installation.mdx | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/installation.mdx b/installation.mdx index 9e70ef3cb..0f5053597 100644 --- a/installation.mdx +++ b/installation.mdx @@ -17,23 +17,21 @@ keywords: ["CLI", "npm", "local development", "Node.js"] Preview your documentation locally, test changes in real-time, and use utilities to maintain your docs. -## Install the CLI +## Install - **Prerequisite**: The CLI requires [Node.js](https://nodejs.org/en) v20.17.0 or higher through v24. LTS versions are preferred. + **Prerequisite**: Requires [Node.js](https://nodejs.org/en) v20.17.0 or higher (LTS preferred). -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 From bc7f81b5251691fdc4459e9709374777efd6561e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 05:57:18 +0000 Subject: [PATCH 3/8] Update installation.mdx --- installation.mdx | 26 ++++---------------------- 1 file changed, 4 insertions(+), 22 deletions(-) diff --git a/installation.mdx b/installation.mdx index 0f5053597..17dfc4bc7 100644 --- a/installation.mdx +++ b/installation.mdx @@ -35,39 +35,21 @@ Preview your documentation locally, test changes in real-time, and use utilities ## 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`. +Your docs will be available at `http://localhost:3000`. Use `npx mint dev` to run without global installation. -Alternatively, if you do not want to install the CLI globally, you can run a one-time script: - -```bash -npx mint dev -``` - -### 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: +**Custom port**: Use `--port` to specify a different 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: +**Preview as a group**: Use `--groups` to preview with specific authentication permissions: ```bash mint dev --groups admin From 268ea291255b5d32fd4ce2b2a4cbcd1dc8ca9bee Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 05:57:26 +0000 Subject: [PATCH 4/8] Update installation.mdx --- installation.mdx | 21 +++++---------------- 1 file changed, 5 insertions(+), 16 deletions(-) diff --git a/installation.mdx b/installation.mdx index 17dfc4bc7..7eeb63a5e 100644 --- a/installation.mdx +++ b/installation.mdx @@ -57,27 +57,16 @@ 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. +This clones the [starter kit](https://github.com/mintlify/starter) and prompts you for a project name and [theme](/customize/themes). -For example, to create a new project in the `docs` directory with the name `my-project` and the theme `linden`, run the following command: +**Flags**: +- `--theme`: Set the theme +- `--name`: Set the project name +- `--force`: Overwrite existing directory ```bash mint new docs --name my-project --theme linden From fb1df8489fbc6985730f2de49e586bade872203b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 05:57:33 +0000 Subject: [PATCH 5/8] Update installation.mdx --- installation.mdx | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/installation.mdx b/installation.mdx index 7eeb63a5e..441089cd8 100644 --- a/installation.mdx +++ b/installation.mdx @@ -71,25 +71,23 @@ This clones the [starter kit](https://github.com/mintlify/starter) and prompts y ```bash mint new docs --name my-project --theme linden ``` -## Update the CLI - -If your local preview is out of sync with what you see on the web in the production version, update your local CLI: +## Update ```bash mint update ``` -If this `mint update` command is not available on your local version, re-install the CLI with the latest version: +If `mint update` is unavailable, reinstall: - - ```bash npm - npm i -g mint@latest - ``` + + ```bash npm + npm i -g mint@latest + ``` - ```bash pnpm - pnpm add -g mint@latest - ``` - + ```bash pnpm + pnpm add -g mint@latest + ``` + ## Additional commands From 8a4ed51524c41987b39730d9843565b3e95c859e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 05:57:42 +0000 Subject: [PATCH 6/8] Update installation.mdx --- installation.mdx | 35 +++++++++-------------------------- 1 file changed, 9 insertions(+), 26 deletions(-) diff --git a/installation.mdx b/installation.mdx index 441089cd8..649915e29 100644 --- a/installation.mdx +++ b/installation.mdx @@ -89,51 +89,34 @@ If `mint update` is unavailable, reinstall: ``` -## Additional commands - -### Find broken links - -Identify any broken internal links with the following command: +## Commands +**Find broken links**: ```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: - +**Check accessibility**: ```bash mint a11y ``` -### Check OpenAPI spec - -Check your OpenAPI file for errors with the following command: - +**Validate OpenAPI spec**: ```bash -mint openapi-check +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: - +**Rename files**: ```bash -mint rename +mint rename ``` -### Migrate MDX endpoint pages - -Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command: - +**Migrate MDX endpoints**: ```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. +See [Migrating from MDX](/guides/migrating-from-mdx) for details. ## Formatting From e0207f3d93e8e6d803e1a08181f686029f53bef6 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 05:57:50 +0000 Subject: [PATCH 7/8] Update installation.mdx --- installation.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/installation.mdx b/installation.mdx index 649915e29..768b6f940 100644 --- a/installation.mdx +++ b/installation.mdx @@ -118,13 +118,11 @@ mint migrate-mdx See [Migrating from MDX](/guides/migrating-from-mdx) for details. -## Formatting +## IDE setup -While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files. +**VS Code / Cursor / Windsurf**: Install [MDX extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode). -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. +**JetBrains**: Install [MDX plugin](https://plugins.jetbrains.com/plugin/14944-mdx) and [Prettier](https://prettier.io/docs/webstorm). ## Troubleshooting From 1d0f0d8d485f65389472f6a005968a9921e656a0 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 05:58:05 +0000 Subject: [PATCH 8/8] Update installation.mdx --- installation.mdx | 49 +++++++++++++++++++----------------------------- 1 file changed, 19 insertions(+), 30 deletions(-) diff --git a/installation.mdx b/installation.mdx index 768b6f940..75eb99349 100644 --- a/installation.mdx +++ b/installation.mdx @@ -127,43 +127,32 @@ See [Migrating from MDX](/guides/migrating-from-mdx) for details. ## 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` - - - **Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, 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. + + Upgrade Node.js, then reinstall: + ```bash + npm uninstall -g mint && npm install -g mint + ``` - - This is likely due to an outdated version of the CLI. - - **Solution:** Run `mint update` to get the latest changes. + + Delete `~/.mintlify` folder and run `mint dev` again. - - 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: + + Run with sudo: ```bash - npm uninstall -g mintlify + sudo npm i -g mint ``` - 2. Clear your npm cache: + + + Update the CLI: ```bash - npm cache clean --force + mint update ``` - 3. Reinstall the new package: + + + If you have both packages installed, uninstall the old one: ```bash + npm uninstall -g mintlify + npm cache clean --force npm i -g mint ```