Simplify installation page

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,209 +15,144 @@
   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
 
 <Info>
-  **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).
 </Info>
 
-Run the following command to install the [CLI](https://www.npmjs.com/package/mint):
-
-  <CodeGroup>
-    ```bash npm
-    npm i -g mint
-    ```
+<CodeGroup>
+  ```bash npm
+  npm i -g mint
+  ```
 
-    ```bash pnpm
-    pnpm add -g mint
-    ```
-  </CodeGroup>
+  ```bash pnpm
+  pnpm add -g mint
+  ```
+</CodeGroup>
 
 ## 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
 ```
 
 ## 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.
-
-<Warning>
-  If you overwrite the current directory, any existing files in the directory will be deleted.
-</Warning>
-
-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:
 
- <CodeGroup>
-    ```bash npm
-    npm i -g mint@latest
-    ```
-
-    ```bash pnpm
-    pnpm add -g mint@latest
-    ```
-  </CodeGroup>
+<CodeGroup>
+  ```bash npm
+  npm i -g mint@latest
+  ```
 
-## Additional commands
+  ```bash pnpm
+  pnpm add -g mint@latest
+  ```
+</CodeGroup>
 
-### 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 <OpenAPI filename or URL>
+mint openapi-check <filename or URL>
 ```
 
-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 <path/to/old-filename> <path/to/new-filename>
+mint rename <old-path> <new-path>
 ```
 
-### 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
 
 <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 title='Error: Could not load the "sharp" module'>
+    Upgrade Node.js, then reinstall:
+    ```bash
+    npm uninstall -g mint && npm install -g mint
+    ```
   </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 title="Unknown error">
+    Delete `~/.mintlify` folder and run `mint dev` again.
   </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 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:
+  <Accordion title="Permission denied">
+    Run with sudo:
     ```bash
-      npm uninstall -g mintlify
+    sudo npm i -g mint
     ```
-    2. Clear your npm cache:
+  </Accordion>
+  <Accordion title="Preview doesn't match production">
+    Update the CLI:
     ```bash
-      npm cache clean --force
+    mint update
     ```
-    3. Reinstall the new package:
+  </Accordion>
+  <Accordion title="mintlify vs. mint package">
+    If you have both packages installed, uninstall the old one:
     ```bash
+    npm uninstall -g mintlify
+    npm cache clean --force
     npm i -g mint
     ```
   </Accordion>