Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 19 additions & 13 deletions installation.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "CLI installation"

Check warning on line 2 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L2

Use 'command-line tool' instead of 'CLI'.
description: "Install the CLI to preview and develop your docs locally"

Check warning on line 3 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L3

Use 'command-line tool' instead of 'CLI'.
---

<img
Expand All @@ -14,10 +14,10 @@
alt="Decorative graphic representing the CLI."
/>

## Installing the CLI

Check warning on line 17 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L17

Use 'command-line tool' instead of 'CLI'.

<Info>
**Prerequisite**: Please install [Node.js](https://nodejs.org/en) before proceeding.

Check warning on line 20 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L20

': P' should be in lowercase.
</Info>

<Steps>
Expand All @@ -36,7 +36,7 @@

</Step>
<Step title="Preview locally.">
Navigate to your docs directory (where your `docs.json` file is located) and execute the following command:

Check warning on line 39 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L39

In general, use active voice instead of passive voice ('is located').

```bash
mint dev
Expand All @@ -46,7 +46,7 @@
</Step>
</Steps>

Alternatively, if you do not want to install the CLI globally, you can run a one-time script:

Check warning on line 49 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L49

Use 'don't' instead of 'do not'.

Check warning on line 49 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L49

Use 'command-line tool' instead of 'CLI'.

```bash
npx mint dev
Expand All @@ -54,13 +54,13 @@

## Updates

If your local preview is out of sync with what you see on the web in the production version, update your local CLI:

Check warning on line 57 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L57

Use 'command-line tool' instead of 'CLI'.

```bash
mint update
```

If this `mint update` command is not available on your local version, re-install the CLI with the latest version:

Check warning on line 63 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L63

Use 'isn't' instead of 'is not'.

Check warning on line 63 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L63

Use 'command-line tool' instead of 'CLI'.

<CodeGroup>
```bash npm
Expand All @@ -74,13 +74,13 @@

## 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:

Check warning on line 77 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L77

Use 'command-line tool' instead of 'CLI'.

Check warning on line 77 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L77

Use 'command-line tool' instead of 'CLI'.

```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:

Check warning on line 83 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L83

Use 'that's' instead of 'that is'.

Check warning on line 83 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L83

Avoid using 'will'.

```mdx
Port 3000 is already in use. Trying 3001 instead.
Expand All @@ -98,37 +98,43 @@

## Additional commands

While `mint dev` is the most commonly used command, there are other commands you can use to manage your documentation.
### Find broken links

### Finding broken links

The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
Identify any broken internal links with the following command:

```bash
mint broken-links
```

### Checking OpenAPI spec
### 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

You can use the CLI to check your OpenAPI file for errors using the following command:
Check your OpenAPI file for errors with the following command:

```bash
mint openapi-check <openapiFilenameOrUrl>
mint openapi-check <OpenAPI filename or URL>
```

You can pass in a filename (for example, `./openapi.yaml`) or a URL (for example, `https://petstore3.swagger.io/api/v3/openapi.json`).
Pass a filename (for example, `./openapi.yaml`) or a URL (for example, `https://petstore3.swagger.io/api/v3/openapi.json`).

Check warning on line 125 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L125

Use parentheses judiciously.

### Renaming files
### Rename files

You can rename and update all references to files using the following command:
Rename and update all references to files with the following command:

```bash
mint rename <oldFilename> <newFilename>
mint rename <path/to/old-filename> <path/to/new-filename>
```

### Migrating MDX endpoint pages
### Migrate MDX endpoint pages

You can migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification using the following command:
Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command:

```bash
mint migrate-mdx
Expand All @@ -138,11 +144,11 @@

## Formatting

While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files.

Check warning on line 147 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L147

Try to avoid using first-person plural like 'we'.

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.

Check warning on line 149 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L149

Try to avoid using first-person plural like 'we'.

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.

Check warning on line 151 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L151

Try to avoid using first-person plural like 'we'.

## Troubleshooting

Expand All @@ -155,7 +161,7 @@
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.

Check warning on line 164 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L164

': G' should be in lowercase.
</Accordion>
<Accordion title="Error: permission denied">
This is due to not having the required permissions to globally install node packages.
Expand All @@ -163,12 +169,12 @@
**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.

Check warning on line 172 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L172

Use 'command-line tool' instead of 'CLI'.

**Solution:** Run `mint update` to get the latest changes.

Check warning on line 174 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L174

': R' should be in lowercase.
</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.

Check warning on line 177 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L177

Use 'command-line tool' instead of 'CLI'.

If you don't use npm or don't see it in the -g list, try `which mint` to locate the installation.

Expand Down
Loading