diff --git a/installation.mdx b/installation.mdx index e17fb6a11..75eb99349 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,63 +15,41 @@ 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. +Preview your documentation locally, test changes in real-time, and use utilities to maintain your docs. -The CLI also has utilities for maintaining your documentation, including commands to rename files, validate OpenAPI specifications, and migrate content between formats. - -## 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 -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 -``` - -### Custom ports +Your docs will be available at `http://localhost:3000`. Use `npx mint dev` to run without global installation. -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 @@ -79,145 +57,102 @@ 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. +This clones the [starter kit](https://github.com/mintlify/starter) and prompts you for a project name and [theme](/customize/themes). -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: +**Flags**: +- `--theme`: Set the theme +- `--name`: Set the project name +- `--force`: Overwrite existing directory ```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 pnpm - pnpm add -g mint@latest - ``` - + + ```bash npm + npm i -g mint@latest + ``` -## Additional commands + ```bash pnpm + pnpm add -g mint@latest + ``` + -### 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. - -## Formatting +See [Migrating from MDX](/guides/migrating-from-mdx) for details. -While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files. +## IDE setup -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. +**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 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 - - 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 ```