Introducing Mintlify: Modern AI Documentation Writer

Welcome to the world of Mintlify, a powerful tool designed to help you create, update, and enhance your documentation with ease. In this comprehensive guide, we'll walk you through everything you need to know about getting started with Mintlify, from deployment and customization to advanced features that will supercharge your documentation. By the end of this guide, you'll have a fully functional documentation site that looks amazing and is easy to maintain.

Deploying Your Docs Repository

Mintlify makes it incredibly easy to deploy your documentation. Here's how you can get started:

Step 1: Clone the Starter Template

Mintlify docs are rendered from MDX files and configurations defined in the starter template. This template provides a solid foundation to build upon.

git clone https://github.com/mintlify/starter
cd starter

Step 2: Install Dependencies

Navigate to your project directory and install the necessary dependencies.

npm install

Step 3: Configure Your Repository

Create a mint.json file in the root of your project directory. This file will contain your core configuration settings.

{
  "name": "Your Project Name",
  "logo": "/path/to/logo.png",
  "favicon": "/path/to/favicon.ico",
  "theme": "venus",
  "backgroundImage": "/path/to/background.jpg"
}

Step 4: Deploy Your Docs

Deploy your documentation by pushing your code to GitHub. Mintlify integrates with GitHub to make source control effortless.

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

Updating Your Docs

Mintlify allows you to easily customize the style, structure, and content of your documentation. Here’s how you can make updates:

Customizing the Style

You can change the appearance of your documentation by updating the mint.json file. For example, you can change the theme or the colors used.

{
  "name": "Your Project Name",
  "logo": {
    "light": "/path/to/light-logo.png",
    "dark": "/path/to/dark-logo.png"
  },
  "favicon": "/path/to/favicon.ico",
  "theme": "prism",
  "colors": {
    "primary": "#3498db",
    "secondary": "#2ecc71"
  }
}

Adding New Pages

To add new pages, simply create new MDX files in the docs directory. Each MDX file represents a page in your documentation.

---
title: New Page
description: This is a new page.
---

# Welcome to the New Page

This is the content of the new page.

Updating Navigation

Update the mint.json file to include new pages in the navigation.

{
  "navigation": [
    {
      "name": "Getting Started",
      "url": "/getting-started"
    },
    {
      "name": "New Page",
      "url": "/new-page"
    }
  ]
}

Supercharging Your Docs

Mintlify supports an array of advanced features like API reference docs, analytics, and versioning to accommodate any of your documentation needs.

API Reference Docs

Mintlify makes it easy to include API reference documentation. You can configure API pages in the mint.json file.

{
  "api": {
    "openapi": "/path/to/openapi.json"
  }
}

Analytics

Track the usage of your documentation by integrating analytics tools. Mintlify supports various analytics platforms.

{
  "analytics": {
    "googleAnalytics": {
      "trackingId": "UA-XXXXXXXXX-X"
    }
  }
}

Versioning

Mintlify allows you to maintain multiple versions of your documentation. This is particularly useful if you need to support different versions of your product.

{
  "versions": [
    "v1.0",
    "v2.0"
  ]
}

Setting Up and Running Mintlify

Follow these steps to install and run Mintlify on your operating system:

Step 1: Install Mintlify

Install Mintlify CLI globally on your machine.

npm install -g mintlify-cli

Step 2: Navigate to the Docs Directory

Navigate to the directory where your mint.json file is located and start the local server.

mintlify start

A local preview of your documentation will be available at http://localhost:3000.

Custom Ports

By default, Mintlify uses port 3000. You can customize the port by using the --port flag.

mintlify start --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.

Updating the CLI

Ensure that your local CLI is up-to-date with the production version. If your local website doesn’t align with the production version, update the CLI.

npm update -g mintlify-cli

Validating Links

The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:

mintlify validate-links

Deployment

Deploy your documentation to a hosting service. If the deployment is successful, you should see the following message:

Deployment successful!

Code Formatting

For the best experience, use extensions on your IDE to recognize and format MDX. If you’re a VSCode user, consider the MDX VSCode extension for syntax highlighting, and Prettier for code formatting.

Configuration with mint.json

Every Mintlify site needs a mint.json file with core configuration settings. This file allows you to customize various aspects of your documentation.

Styling

Configure the styling of your documentation site.

{
  "name": "Your Project Name",
  "logo": {
    "light": "/path/to/light-logo.png",
    "dark": "/path/to/dark-logo.png"
  },
  "favicon": "/path/to/favicon.ico",
  "theme": "quill",
  "colors": {
    "primary": "#3498db",
    "secondary": "#2ecc71"
  }
}

Structure

Define the structure of your documentation.

{
  "navigation": [
    {
      "name": "Getting Started",
      "url": "/getting-started"
    },
    {
      "name": "API Reference",
      "url": "/api-reference"
    }
  ],
  "versions": [
    "v1.0",
    "v2.0"
  ],
  "anchors": [
    {
      "icon": "link",
      "color": "#3498db",
      "url": "/#section"
    }
  ],
  "tabs": [
    {
      "name": "Writing Content",
      "url": "content"
    },
    {
      "name": "API References",
      "url": "api-playground"
    }
  ]
}

API Configurations

Configure API settings for your documentation.

{
  "api": {
    "openapi": [
      "/path/to/openapi1.json",
      "/path/to/openapi2.json"
    ]
  }
}

Integrations

Add third-party integrations to your documentation.

{
  "integrations": {
    "slack": {
      "webhookUrl": "https://hooks.slack.com/services/XXXX/YYYY/ZZZZ"
    }
  },
  "analytics": {
    "googleAnalytics": {
      "trackingId": "UA-XXXXXXXXX-X"
    }
  }
}

Redirects

Configure paths to permanently redirect to another path.

{
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path"
    }
  ]
}

Search Engine Optimization

Set up SEO settings for your documentation.

{
  "seo": {
    "indexHiddenPages": true
  }
}

Enabling Analytics

Set your analytics keys in mint.json. You can add an unlimited number of analytics integrations for free.

{
  "analytics": {
    "amplitude": {
      "apiKey": "required"
    },
    "clearbit": {
      "publicApiKey": "required"
    },
    "fathom": {
      "siteId": "required"
    },
    "ga4": {
      "measurementId": "required"
    },
    "gtm": {
      "tagId": "required"
    },
    "hotjar": {
      "hjid": "required",
      "hjsv": "required"
    },
    "koala": {
      "publicApiKey": "required"
    },
    "logrocket": {
      "appId": "required"
    },
    "mixpanel": {
      "projectToken": "required"
    },
    "pirsch": {
      "id": "required"
    },
    "plausible": {
      "domain": "required"
    },
    "posthog": {
      "apiKey": "required",
      "apiHost": "optional"
    }
  }
}

Conclusion

Mintlify provides a powerful and flexible platform for creating and managing your documentation. With its easy-to-use features and extensive customization options, you can create a documentation site that meets your needs and enhances the user experience. Whether you're just getting started or looking to take your documentation to the next level, Mintlify has the tools you need. If you need support or want to give feedback, join our community or drop us an email at support@mintlify.com.

Happy documenting!