Skip to content
Merged
Show file tree
Hide file tree
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
2 changes: 2 additions & 0 deletions installation.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
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: "Use the CLI to preview docs locally, test changes in real-time, and catch issues before deploying your documentation site."
keywords: ["CLI", "npm", "local development", "Node.js"]

Check warning on line 4 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L4

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

<img
Expand All @@ -15,14 +15,14 @@
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.

Check warning on line 18 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L18

Use 'capability' or 'feature' instead of 'functionality'.

The CLI also has utilities for maintaining your documentation, including commands to rename files, validate OpenAPI specifications, and migrate content between formats.

Check warning on line 20 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L20

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

## Install the CLI

<Info>
**Prerequisite**: The CLI requires [Node.js](https://nodejs.org/en) v20.17.0 or higher through v24. LTS versions are preferred.

Check warning on line 25 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L25

': T' should be in lowercase.

Check warning on line 25 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L25

Spell out 'LTS', if it's unfamiliar to the audience.

Check warning on line 25 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L25

In general, use active voice instead of passive voice ('are preferred').
</Info>

Run the following command to install the [CLI](https://www.npmjs.com/package/mint):
Expand All @@ -39,7 +39,7 @@

## Preview locally

To generate a local preview, navigate to your documentation directory (where your `docs.json` file is located) and run the following command:

Check warning on line 42 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L42

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

```bash
mint dev
Expand All @@ -47,7 +47,7 @@

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:

Check warning on line 50 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L50

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

Check warning on line 50 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L50

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

```bash
npx mint dev
Expand All @@ -55,13 +55,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 58 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L58

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

Check warning on line 58 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L58

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 64 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L64

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

Check warning on line 64 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L64

Avoid using 'will'.

```mdx
Port 3000 is already in use. Trying 3001 instead.
Expand All @@ -85,13 +85,13 @@
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.

Check warning on line 88 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L88

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

Check warning on line 88 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L88

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

<Warning>
If you overwrite the current directory, any existing files in the directory will be deleted.

Check warning on line 91 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L91

Avoid using 'will'.

Check warning on line 91 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L91

In general, use active voice instead of passive voice ('be deleted').
</Warning>

The CLI tool prompts you for a project name and [theme](/customize/themes) to finish setting up your project.

Check warning on line 94 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L94

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

You can run `mint new` with the following flags:

Expand All @@ -104,15 +104,15 @@
```bash
mint new docs --name my-project --theme linden
```
## Update the CLI

Check warning on line 107 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L107

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

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 109 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L109

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 115 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L115

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

Check warning on line 115 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L115

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

<CodeGroup>
```bash npm
Expand All @@ -134,6 +134,8 @@
mint broken-links
```

The command ignores files matching [.mintignore](/organize/mintignore) patterns. Links that point to ignored files are reported as broken.

Check warning on line 137 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L137

In general, use active voice instead of passive voice ('are reported').

### 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:
Expand All @@ -150,7 +152,7 @@
mint openapi-check <OpenAPI filename or URL>
```

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

Check warning on line 155 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L155

Use parentheses judiciously.

### Rename files

Expand All @@ -172,11 +174,11 @@

## Formatting

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

Check warning on line 177 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L177

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 179 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L179

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 181 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L181

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

## Troubleshooting

Expand All @@ -189,7 +191,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 194 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L194

': 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 @@ -197,12 +199,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 202 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L202

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

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

Check warning on line 204 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L204

': 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 207 in installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

installation.mdx#L207

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
1 change: 1 addition & 0 deletions organize/mintignore.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
title: "Mintignore"

Check warning on line 2 in organize/mintignore.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/mintignore.mdx#L2

Did you really mean 'Mintignore'?
description: "Exclude specific files and directories from your published documentation."
keywords: ["exclude", "ignore", "gitignore", "drafts", "private"]
---

The `.mintignore` file allows you to exclude specific files and directories from being processed and published to your documentation site.

Check warning on line 7 in organize/mintignore.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/mintignore.mdx#L7

In general, use active voice instead of passive voice ('being processed').

Use `.mintignore` to keep drafts, internal notes, and source files out of your public documentation while maintaining them in your repository.

Expand All @@ -31,6 +31,7 @@
- Don't appear in your published documentation.
- Aren't indexed for search.
- Aren't accessible to visitors.
- Are ignored by [broken link checks](/installation#find-broken-links). Links that point to ignored files are broken.

Check warning on line 34 in organize/mintignore.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/mintignore.mdx#L34

In general, use active voice instead of passive voice ('Are ignored').

Check warning on line 34 in organize/mintignore.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/mintignore.mdx#L34

In general, use active voice instead of passive voice ('are broken').

## Default ignored patterns

Expand All @@ -47,7 +48,7 @@

<Note>
Unlike [hidden pages](/organize/hidden-pages), files excluded by `.mintignore`
are completely removed from your site and cannot be accessed by URL.

Check warning on line 51 in organize/mintignore.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/mintignore.mdx#L51

Use 'can't' instead of 'cannot'.

Check warning on line 51 in organize/mintignore.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/mintignore.mdx#L51

In general, use active voice instead of passive voice ('be accessed').
</Note>

## Pattern syntax
Expand All @@ -60,4 +61,4 @@
| `*.draft.mdx` | Excludes all files ending in `.draft.mdx` |
| `private-notes.md` | Excludes a specific file |
| `**/internal/**` | Excludes any `internal` directory at any level |
| `!important.mdx` | Negates a previous pattern (includes the file) |

Check warning on line 64 in organize/mintignore.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/mintignore.mdx#L64

Use parentheses judiciously.