Skip to main content
The web editor lets you work without installing anything. If you prefer your own editor or want to test changes locally, you’ll need Git, Node.js, the Mintlify CLI, and a local copy of the repository. By the end of this lesson, you’ll have your docs running at localhost:3000.

​
Before you begin

Make sure you have:
  • Access to your documentation repository on GitHub. If Mintlify created the repository for you during onboarding, clone it to your own account first.
  • Git installed on your computer
  • Node.js v20.17.0 or later
  • A terminal and a code editor
You can confirm that Git and Node.js are available by running:
Check your installed versions
If either command fails, or Node.js is older than v20.17.0, install or update that tool before continuing. See the Mintlify CLI installation guide for details.

​
Clone your repository

Cloning downloads the repository and connects your local copy to GitHub. On your repository’s GitHub page, select Code and copy the HTTPS URL. Then run:
Replace the example URL and directory with your own. Run ls to check that you’re in the right place. You should see docs.json and your documentation files.
If GitHub asks you to authenticate, follow its prompt. Depending on your organization, you may use a browser sign-in, a personal access token, or SSH.

​
Install the Mintlify CLI

Install the CLI globally so the mint command is available from any documentation project:
Then confirm the installation:
You can also run the CLI without a global installation by using npx mint in place of mint.

​
Start a local preview

From the directory that contains docs.json, run:
The preview opens in your browser at http://localhost:3000. Leave the command running while you work. When you save a file, the preview reloads with your changes.
If you use VS Code or Cursor, the Mintlify MDX extension can show the preview in a panel beside your editor.
If port 3000 is already in use, the CLI chooses another available port and prints its address in the terminal.

​
Make a test edit

Open an MDX page and change a sentence. Save the file, then check the local preview. Before committing anything, inspect what changed:
git status lists changed and untracked files. git diff shows the exact line-by-line edits that you haven’t staged yet. Together, they help you catch an accidental change before it reaches a commit. You can now restore the sentence or keep it for the workflow lesson.

​
Common setup problems

mint: command not found Restart your terminal after installing the CLI. If the command still isn’t available, use npx mint dev or check where npm installs global packages. The preview shows a site you don’t recognize, or a new docs.json appears If you run mint dev in a directory without a docs.json file, the CLI generates one from the folder structure. Stop the preview, delete the generated file if you don’t want it, and run pwd and ls to find the directory that contains your real docs.json. The local preview looks different from your live site Run mint update to get the latest version of the CLI, then restart the preview. GitHub rejects your clone or push Confirm that you have access to the repository and that GitHub authentication is working. If you can clone but can’t push, you may have read access instead of write access. Next up: Workflow overview—turn your local edit into a branch, commit, pull request, preview, and published update.