How to publish your open source project's docs on Mintlify for free

Key takeaways

• It takes less than an afternoon, and a coding agent does most of the work.
• Existing .md files work. The agent adds a config file and fixes paths.
• Docs stay in a docs/ folder in the repository.
• Contributors still edit Markdown and open pull requests.
• Publish free on Starter, then apply for the OSS Program to get Pro free.

Most open source projects already have some docs, usually a README and a few Markdown files in a docs/ folder. Moving them to Mintlify takes less than an afternoon, because a coding agent can handle the Markdown changes for you. Your files stay in your repository, and contributors keep sending pull requests the same way they do today.

In this guide, we'll walk through the agent-led setup, how to check the agent's work, how to connect your repository, and how to apply for the Mintlify OSS Program to unlock Pro for free.

Let a coding agent do the conversion

1. Install the CLI and the Mintlify agent skill

Before you start, make sure you have Node.js v20.17.0 or newer, since the Mintlify CLI needs it. From your project root, check your Node version and install the CLI from the mint package. Don't install the older mintlify package by mistake.

node --version
npm i -g mint

Next, install the Mintlify agent skill. It teaches your coding agent how Mintlify projects work, including docs.json, navigation, page rules, and the CLI.

npx skills@latest add \
  https://github.com/mintlify/docs/tree/main/agent-context/context/skills/mintlify \
  --skill mintlify

When the command prompts you, pick your agent and scope. Then start a new agent session so the skill loads.

2. Ask the agent to convert your docs

Create a branch, open Claude Code, Cursor, or Codex in your project root, and paste a prompt like this one:

Use mintlify to turn the Markdown in docs/ into a Mintlify site.
- Keep the content of every page as it is. Don't rewrite or reorganize it.
- Create docs/docs.json and build the navigation from the existing files.
  If there's an old sidebar config (mkdocs.yml, sidebars.js, SUMMARY.md),
  follow its order.
- Add a title in frontmatter where a page has none.
- Convert directives from the old tool (:::note, !!! note, {% hint %})
  to Mintlify callouts and components.
- Copy remote images into the repo and fix image and link paths.
- If the docs are already published, add redirects for every URL that changes.
- Run mint validate and mint broken-links, then search for leftover syntax
  from the old tool and fix it.
- Don't commit, push, or publish.

The skill already knows how Mintlify projects work, so the prompt only covers what's specific to moving existing docs: syntax from your old tool, images, and the URLs people already link to.

If your docs are already live with another tool, Mintlify has a migration guide for Docusaurus, ReadMe, GitBook, and any other platform. Each one maps the old syntax and navigation to Mintlify, so it's worth handing the right guide to your agent along with the prompt. For a site that's already public, you can also scrape the rendered pages into an empty folder as a starting point:

mkdir mintlify-migration
cd mintlify-migration
npx -p @mintlify/scraping@latest -p puppeteer mintlify-scrape section https://docs.your-project.org

Check the agent's work

The diff can look big, since moving files around and fixing paths touches a lot of lines. Most of it is mechanical, though, so focus your review on these changes.

A new docs/docs.json. This config file only needs four fields, so a minimal one looks like this:

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "your-project",
  "colors": {
    "primary": "#0D9373"
  },
  "navigation": {
    "groups": [
      {
        "group": "Get started",
        "pages": ["index", "installation", "configuration"]
      }
    ]
  }
}

Each entry in pages is a file path relative to docs/, without the extension. A page that isn't listed doesn't appear in the sidebar.

Optional frontmatter. All frontmatter fields are optional, and if a page has no title, Mintlify generates one from the file name. Where it helps, the agent adds a short block like this one:

---
title: 'Installation'
description: 'Install your-project with npm, Homebrew, or from source.'
---

Path fixes. Mintlify page links have no file extension, and images use root-relative paths from your docs directory:

See the [configuration reference](/configuration).

![Architecture diagram](/images/architecture.png)

Redirects. If your docs were already published, the agent adds redirects to docs.json for every page whose URL changed. That way, links in old issues, blog posts, and Stack Overflow answers keep working.

A homepage. Mintlify ignores README.md, CONTRIBUTING.md, CHANGELOG.md, and LICENSE.md by default, so if docs/ only had a README, the agent adds an index.md.

The words on each page shouldn't change, so if the agent rewrote any content, push back. It's also worth searching for leftover syntax from your old tool, like :::, !!!, or {%, since it shows up as plain text or breaks the build.

3. Preview the site locally

Run the preview from the directory that contains docs.json:

cd docs
mint dev

Open http://localhost:3000 and click through every sidebar group. Make sure the images load and the page order makes sense for someone new to the project.

4. Validate the build and check links

Run the two CLI checks yourself, even if the agent already ran them:

mint validate
mint broken-links

mint validate builds the site in strict mode and fails on any warning or error, while mint broken-links reports internal links that don't resolve. Once both pass, open a pull request and merge it like any other change.

Connect the repository and deploy

5. Create an account and install the GitHub App

Sign up for Mintlify and finish onboarding. Because the free Starter plan includes hosting and a custom domain, your site can go live before the OSS Program reviews your application.

Then install the Mintlify GitHub App from the dashboard's Git settings. Keep two things in mind:

• You need owner or administrator permissions on the repository. Otherwise, a repository owner must approve the installation request.
• When GitHub asks which repositories to grant access to, select Only select repositories and pick your project repository.

6. Choose the repository, branch, and docs folder

In Git settings, select your organization, repository, and production branch, usually main. Because docs.json lives in docs/, follow the monorepo setup:

1. Turn on the docs.json is in a subdirectory toggle.
2. Enter /docs as the path, with no trailing slash.
3. Click Save changes. This starts a deployment from that path.

Mintlify only reads that folder, so the rest of your repository stays exactly as it is.

7. Verify the live site

Your site deploys to a .mintlify.site subdomain, and you can confirm the address from the terminal:

mint status

mint status shows your email, organization, and subdomain. If it says there's no session, run mint login first. You'll also find the URL on the Overview page of the dashboard. Open https://<your-subdomain>.mintlify.site and check the same pages you checked locally.

8. Add a custom domain if you have one

This step is optional. If you want your docs at an address like docs.your-project.org, add the domain in the dashboard and create the DNS records it shows you. If that domain already serves your old docs, keep the old site running until the Mintlify site checks out, then switch over. The custom domain setup walks through a zero-downtime cutover.

What changes for contributors

For contributors, nothing changes. They edit Markdown in docs/, open a pull request, and a maintainer reviews it. When the pull request merges into the production branch, Mintlify deploys the update.

Pro also adds preview deployments. For each pull request into the deployment branch, the Mintlify bot posts a preview URL that updates with every commit. Pull requests from forks are the exception. Because a preview runs the contributor's code, a maintainer has to approve it first.

The pricing page lists preview deployments under Pro, so an approved OSS Program project gets them. On any plan, though, you can run the same CLI checks in GitHub Actions on every pull request:

name: Docs checks

on:
  pull_request:
    paths:
      - 'docs/**'

jobs:
  docs-checks:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: docs
    steps:
      - uses: actions/checkout@v4
      - name: Install the Mintlify CLI
        run: npm i -g mint
      - name: Validate the build
        run: mint validate
      - name: Check internal links
        run: mint broken-links

Apply for the OSS Program

9. Submit the application

Once your site is live, apply for the Mintlify OSS Program. If you're approved, you get Mintlify Pro free, forever, with 5,000 AI credits a month for the Assistant and automations.

Your project needs to meet all three criteria on the program page:

• It uses a recognized open source license, such as MIT, Apache 2.0, or GPL.
• It isn't venture-backed or funded by revenue.
• No for-profit company owns it or does most of its maintenance.

Keep in mind that submitting an application isn't the same as being approved. Your site stays live on Starter during the review, and nothing in your repository changes when Pro starts.

Frequently Asked Questions

Can a coding agent do the migration?

Yes. With the Mintlify agent skill installed, Claude Code, Cursor, or Codex can create docs.json, build navigation from your files, add frontmatter, and fix links and image paths. You still review the diff, preview it with mint dev, and connect GitHub in the browser.

Do I have to move my docs out of my repository?

No. Mintlify builds from the repository and branch you connect, and it can read from a subdirectory such as docs/. Your Markdown stays right next to your code.

Can I keep plain .md files, or must they be .mdx?

Plain .md files work fine, since Mintlify supports both formats. A page only needs to become .mdx when it uses components such as Tabs or Cards. For the differences, read Markdown vs MDX.

Can contributors still edit through pull requests?

Yes. Contributors open pull requests as they do today, and merges to the production branch deploy automatically. On Pro, each pull request also gets a preview URL. Fork pull requests need a maintainer's approval before the preview builds.

Do I need OSS Program approval to publish?

No. Any project can publish on the free Starter plan right away. The OSS Program is a separate application, and it upgrades eligible projects to Pro.

Is Mintlify open source?

No. Mintlify is a hosted, proprietary platform, but the docs content stays as Markdown files in the project's own repository, under the project's license.