Skip to content

development.mdx

Latest commit

 

History

History
114 lines (75 loc) · 2.54 KB

development.mdx

File metadata and controls

114 lines (75 loc) · 2.54 KB
title Dev Environment
description How I run this docs site locally and my setup for editing
icon laptop-code
og:image /images/hero-light.png

import Prerequisites from '/snippets/prerequisites.mdx';

Prerequisites

If you have a legacy `mint.json` file, run the Mintlify upgrade command to convert it to `docs.json` and delete the old file.

Install & Run

npm i -g mintlify
yarn global add mintlify

Then navigate to wherever docs.json lives and start the dev server:

mintlify dev

Open localhost:3000 and you're live.

Custom Ports

Mintlify uses port 3000 by default. To use a different port:

mintlify dev --port 3333

If the port is already in use, it automatically picks the next one:

Port 3000 is already in use. Trying 3001 instead.

Keeping the CLI Updated

Each CLI version is tied to a specific Mintlify release. If the local preview looks different from production, update:

npm i -g mintlify@latest
yarn global upgrade mintlify

Validating Links

Before pushing, run this to catch any broken internal links:

mintlify broken-links

Deployment

Push to main and the Mintlify GitHub app deploys automatically. You can also deploy manually from the dashboard.

If the deploy succeeds, you'll see this on the commit:

IDE Setup

I use VSCode with these extensions:

  • MDX — syntax highlighting for .mdx files
  • Prettier — auto-formatting

Troubleshooting

This is usually an outdated Node version:
1. Remove mintlify: `npm remove -g mintlify`
2. Upgrade to Node v19+
3. Reinstall: `npm install -g mintlify`

Delete the `~/.mintlify` folder and run `mintlify dev` again. This clears the local cache and fixes most mystery issues.
Check the [CLI changelog](https://www.npmjs.com/package/mintlify?activeTab=versions) if you want to see what changed between versions.