Skip to main content
Following a docs-as-code workflow allows us to treat documentation with the same rigor as our bot logic. We use the Mintlify CLI to ensure all content is validated before reaching production.

​
Install the CLI

​
Prerequisites

  • Node.js v20.17.0+ (LTS versions recommended)

​
Installation

​
Contributor commands

If you are contributing content, use these commands (via npm wrappers) to verify your work.

​
Local preview

Run this to start a live-reloading server at localhost:3000.

​
Validation

Run this to catch structural errors or configuration issues in docs.json.
Run this when you add or rename pages to confirm all internal paths still resolve.

​
Maintainer commands

These commands are typically reserved for the Owner or Team to manage the documentation infrastructure.

​
Update CLI

If the local preview differs from production, sync your CLI version:

​
Create or scrape content

For initializing new sections or migrating documentation from external sources:

​
Formatting

To maintain a consistent style, we recommend using the following extensions for MDX syntax highlighting and automated formatting:
  • Cursor / VS Code: MDX Extension and Prettier.
  • JetBrains: MDX Plugin and Prettier.

​
Troubleshooting

This usually happens due to an outdated Node.js version.
  1. Uninstall: npm uninstall -g mint
  2. Upgrade to Node.js v20.17.0+.
  3. Reinstall: npm install -g mint
Solution: Delete the ~/.mintlify folder in your user home directory and run npm run docs:dev again.
This occurs if you lack global install permissions. Solution: Use sudo npm i -g mint on macOS/Linux, or run your terminal as Administrator on Windows.
If you have both mint and mintlify packages installed, they will conflict. Solution:
This happens when a corporate firewall or VPN blocks the CLI from downloading the client app. Solution: Add releases.mintlify.com to your network allowlist.

Contribution Guide

Use the docs workflow and PR guidance when you update the site.

Testing Strategies

Validate docs-related changes and bot changes with the existing test suite.

Environment Variables

Confirm the settings that your local setup depends on.

Quickstart

Revisit the end-to-end setup path after you validate the docs locally.