Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sorgm/data-architecture-docs/llms.txt

Use this file to discover all available pages before exploring further.

Prerequisites:
  • Node.js version 19 or higher
  • A docs repository with a docs.json file
Follow these steps to install and run Mintlify on your operating system.
1

Install the Mintlify CLI

Install the CLI globally using npm:
npm i -g mint
This gives you access to the mint command for local development and validation.
2

Preview locally

Navigate to your docs directory where your docs.json file is located, and run the following command:
mint dev
A local preview of your documentation will be available at http://localhost:3000.
Your preview updates automatically as you edit files. No need to restart the server!

​
Custom ports

By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the --port flag. For example, to run Mintlify on port 3333, use this command: 
mint dev --port 3333
If you attempt to run Mintlify on a port that’s already in use, it will use the next available port: 
Port 3000 is already in use. Trying 3001 instead.

​
CLI commands

The Mintlify CLI provides several useful commands for managing your documentation:

​
Update CLI version

Keep your CLI up to date to ensure your local preview matches production: 
npm mint update
Each CLI release is associated with a specific version of Mintlify. If your local preview does not align with the production version, update the CLI.
The CLI can assist with validating links in your documentation. To identify any broken links, use the following command: 
mint broken-links
This command crawls your entire documentation site and reports any broken internal or external links.

​
Best practices

Use AI-assisted writing

Install the Mintlify skill for your AI coding tool:
npx skills add https://mintlify.com/docs

Code formatting

Use the MDX VSCode extension for syntax highlighting and Prettier for formatting.

​
Deployment

When you push changes to your repository, the Mintlify GitHub app automatically deploys your updates. If the deployment is successful, you should see the following:
Screenshot of a deployment confirmation message that says All checks have passed.
Changes are deployed to production automatically after pushing to the default branch.

​
Troubleshooting

This may be due to an outdated version of node. Try the following:
  1. Remove the currently-installed version of the CLI:
npm remove -g mint
  1. Upgrade to Node v19 or higher.
  2. Reinstall the CLI: 
npm i -g mint
Go to the root of your device and delete the ~/.mintlify folder. Then run mint dev again:
rm -rf ~/.mintlify
mint dev
Run mint update to ensure you have the most recent version of the CLI:
npm mint update
If the issue persists, try removing and reinstalling the CLI.
Make sure you are running in a folder with a valid docs.json file. The CLI must be run from the root of your documentation directory.Verify your docs.json navigation includes the page path:
{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["index", "quickstart", "development"]
          }
        ]
      }
    ]
  }
}
If you continue to experience issues, check the CLI changelog for breaking changes or known issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us