Mintlify Getting Started: Account Setup & First Docs (2026)

Getting started overview

Mintlify provides tools to create, host, and maintain developer documentation, including API references and guides. This getting started guide focuses on the initial steps required to set up an account, configure your local environment, and publish your first documentation project. The primary method for interaction is through the Mintlify Command Line Interface (CLI) and integration with version control systems like GitHub.

The process generally involves:

1. Account Creation: Signing up for a Mintlify account.
2. Local Setup: Installing the Mintlify CLI on your development machine.
3. Project Initialization: Creating a new documentation project using the CLI.
4. Content Creation: Adding your documentation content, often in Markdown format.
5. Preview and Publish: Locally previewing your documentation and then deploying it.

Mintlify is designed for developers and technical writers who need to manage documentation efficiently, supporting features like auto-generated API references from OpenAPI specifications and an AI assistant for content drafting. For a comprehensive overview of its features, refer to the Mintlify documentation introduction.

Quick Reference Table

Create an account and get keys

To begin using Mintlify, you need to create an account. Mintlify offers a free tier for individuals and small teams, making it accessible for initial exploration. Account creation typically involves signing up through their web interface, often with options to use existing GitHub or Google accounts for streamlined registration.

1. Navigate to the Mintlify website: Go to the Mintlify homepage.
2. Sign Up: Look for a "Get Started" or "Sign Up" button. You will likely be prompted to create an account using an email address, or by authenticating with GitHub or Google. Using GitHub is often recommended as Mintlify integrates closely with GitHub repositories for documentation management and deployments.
3. Dashboard Access: Upon successful registration, you will be redirected to your Mintlify dashboard. This dashboard is where you can manage your projects, team members, and deployments.

Mintlify primarily uses GitHub integration for authentication and deployment, rather than traditional API keys for direct content publishing. When you initialize a project and link it to a GitHub repository, Mintlify uses your GitHub account's permissions to access and deploy your documentation. For advanced scenarios or programmatic interactions, some services might offer API tokens, but for getting started with documentation, GitHub integration is the standard approach. For detailed steps on connecting your GitHub repository, consult the Mintlify deployment settings documentation.

Your first request

While Mintlify doesn't involve making a "first API request" in the traditional sense of consuming an external API, the equivalent is to initialize your first documentation project and publish it. This involves using the Mintlify CLI.

Step 1: Install the Mintlify CLI

Open your terminal or command prompt and install the Mintlify CLI globally using npm:

npm install -g mintlify

Verify the installation by checking the version:

mintlify --version

This command should output the installed Mintlify CLI version, confirming that the tool is ready for use.

Step 2: Initialize a New Project

Navigate to the directory where you want to create your documentation project. Then, run the initialization command:

mintlify init

The CLI will guide you through a series of prompts:

• Project name: Enter a name for your documentation project (e.g., my-first-docs).
• GitHub repository: You'll be asked to connect to a GitHub repository. This step is crucial for deployment. If you don't have one yet, you can create a new empty repository on GitHub and then link it. Mintlify will guide you to authenticate with GitHub in your browser. This authentication securely links your local CLI to your Mintlify account and GitHub repository, enabling seamless deployments. OAuth 2.0 is commonly used for such third-party application access to GitHub resources, as detailed in GitHub's documentation on authorizing OAuth Apps.

After initialization, Mintlify creates a new directory (e.g., my-first-docs) containing a basic documentation structure, including configuration files (mint.json) and a docs/ directory with example Markdown files.

Step 3: Add and Modify Content

Navigate into your newly created project directory:

cd my-first-docs

Open the docs/index.mdx file (or any other .md file in the docs/ directory) in your preferred text editor. Modify the content. For example, change "Hello World" to "Welcome to my first Mintlify docs!". You can also add new Markdown files to create additional pages.

Step 4: Preview Your Documentation

To see your changes in real-time, run the development server:

mintlify dev

This command starts a local development server, typically accessible at http://localhost:3000. Open this URL in your web browser to view your documentation. Any changes you make to your Markdown files will automatically refresh in the browser.

Step 5: Deploy Your Documentation

Once you are satisfied with your documentation, you can deploy it. Since you linked your project to a GitHub repository during initialization, the primary deployment method is to push your changes to that repository. Mintlify's GitHub integration will automatically detect the push and trigger a deployment.

git add .
git commit -m "Initial documentation deployment"
git push origin main

Alternatively, you can manually trigger a deployment from the CLI (ensure you are logged in via the CLI and linked to your project):

mintlify deploy

After deployment, your documentation will be accessible at the URL provided by Mintlify, typically in the format [your-project-name].mintlify.app. You can find this URL in your Mintlify dashboard under the project settings.

Common next steps

After successfully deploying your first Mintlify documentation, consider these common next steps to enhance your project:

• Customize Appearance: Modify the mint.json configuration file to change themes, colors, and navigation structure. Mintlify provides extensive options for branding and layout adjustments, as detailed in their project settings documentation.
• Integrate API References: If you are documenting an API, import your OpenAPI (Swagger) specification file. Mintlify can automatically generate interactive API reference documentation from these files. Place your .json or .yaml OpenAPI file in your project and configure its path in mint.json.
• Add More Content: Expand your documentation with more guides, tutorials, and examples. Organize content using folders and update the navigation in mint.json.
• Team Collaboration: Invite team members to collaborate on your documentation project through the Mintlify dashboard. You can manage roles and permissions to control access.
• Leverage AI Assistant: Utilize Mintlify's integrated AI assistant to help draft new content, summarize existing sections, or improve clarity and grammar. This feature can accelerate content creation and refinement.
• Set Up Custom Domain: For a professional appearance, configure a custom domain for your documentation site (e.g., docs.yourcompany.com). This is managed through your Mintlify dashboard and requires updating DNS records with your domain registrar.
• Explore Advanced Features: Investigate features like content versioning, search functionality, and analytics to further optimize your documentation portal.

Troubleshooting the first call

When setting up your first Mintlify project, you might encounter a few common issues. Here's how to troubleshoot them:

• CLI Installation Issues:
  • "mintlify command not found": Ensure Node.js and npm are installed correctly. Re-run npm install -g mintlify. Sometimes, administrative privileges are required (sudo npm install -g mintlify on macOS/Linux or running Command Prompt as administrator on Windows). Check your system's PATH environment variable to ensure npm's global bin directory is included.
  • Version conflicts: If you have multiple Node.js versions, use a version manager like nvm to switch to a compatible version.
• GitHub Authentication Problems:
  • Authorization failed during mintlify init: Ensure you are logged into the correct GitHub account in your web browser when prompted. Clear browser cookies or try in an incognito window. Verify that Mintlify has been granted the necessary permissions in your GitHub authorized OAuth Apps settings.
  • Repository not found: Double-check the repository name and owner during initialization. Ensure the repository exists and your GitHub account has appropriate access.
• Local Development Server (mintlify dev) Issues:
  • Port already in use: If http://localhost:3000 is already in use by another application, Mintlify might suggest an alternative port. You can also specify a port manually: mintlify dev --port 8000.
  • Changes not reflecting: Save your Markdown files after making edits. Sometimes, a full restart of mintlify dev might be necessary if the hot-reloading feature encounters an issue.
  • Build errors in terminal: Read the error messages carefully. They often point to syntax issues in Markdown, configuration errors in mint.json, or problems with linked assets.
• Deployment Failures:
  • GitHub Action failures: If deploying via GitHub, check the "Actions" tab in your GitHub repository for detailed logs of the Mintlify deployment workflow. Common issues include incorrect branch configurations or missing permissions.
  • mintlify deploy not working: Ensure your project is correctly linked to your Mintlify account and a GitHub repository. Check your network connection.
  • Content not appearing on live site: Verify that the correct branch is being deployed (usually main or master). Clear your browser cache or try accessing the live site in an incognito window to rule out caching issues.