Skip to main content
Git tracks your changes. GitHub is where your team collaborates on them — it’s where pull requests happen, where the Mintlify bot runs checks, and where preview deployments are generated before anything goes live. Before you can publish documentation with Mintlify, two things need to be in place: a GitHub repository to store your content, and the Mintlify GitHub app installed so that Mintlify can detect changes and rebuild your site automatically. This lesson walks through getting both set up from scratch.

​
Create your Mintlify account

Go to mintlify.com/start and sign up. During onboarding, you’ll connect your GitHub account — this is what lets Mintlify read your repository and deploy your site when changes are merged. If you don’t have a GitHub account yet, you’ll need to create one first. A free account is all you need.

​
Set up your repository

When you connect your GitHub account, Mintlify gives you two options: Let Mintlify create a repository for you. Mintlify creates a private repository, installs the GitHub app, and configures everything automatically. Your site is live within minutes. This is the fastest way to get started, and you can always rename the repository or transfer it to your organization later. Connect an existing repository. If you already have a GitHub repository where your documentation should live, you can connect it instead. Mintlify will walk you through installing the GitHub app on that repository. Either way, once the connection is made, Mintlify deploys your documentation site automatically. You’ll find the URL — something like your-project.mintlify.app — on the Overview page of your Mintlify dashboard.

​
What the GitHub app does

The Mintlify GitHub app is what makes the workflow function. When it’s installed on your repository, it:
  • Rebuilds your site automatically when changes are merged into your main branch
  • Generates a preview deployment for every pull request, so you can review changes before they go live
  • Runs checks on pull requests to catch issues like broken links or missing metadata before they reach your live site
Without the GitHub app, Mintlify has no way to know when your repository changes. Installing it is a one-time step — after that, the connection is maintained automatically.

​
What’s in your repository

Once your repository is set up, it contains at minimum a docs.json file and an initial page. The docs.json file is the configuration file for your Mintlify site — it controls your navigation structure, site name, colors, and other settings. Every page you add, every section you create, starts here. From this point, you’re ready to start editing. Next up: Access and permissions — who can do what in your repository, and how to make sure the right people have the right level of access.