Skip to main content
Developer documentation helps people understand and integrate with your product. Good documentation helps people do more with your product, reduces support burden, speeds up adoption, and improves developer experience. Mintlify provides infrastructure built for developer documentation.
  • API reference generation: Generate interactive API references from OpenAPI specifications that let developers test endpoints in your documentation.
  • Code blocks with explanations: The assistant explains code examples in context, helping developers understand implementation details.
  • Git sync: Keep documentation in sync with your codebase using GitHub or GitLab.
  • Versioning: Maintain documentation for multiple versions so developers on older versions can still find accurate information.

​
Prerequisites

If you haven’t created a Mintlify project yet, see the Quickstart to deploy your site.
  • Your API specification in OpenAPI format (if documenting an API)
  • A Git repository for your documentation
  • Admin access to your Mintlify organization

​
Migrate existing documentation

If you’re creating documentation from scratch, skip to Plan your documentation structure.

​
Audit existing content

Review your current documentation to understand what you have and what you need to migrate.
  • API reference: Is it generated from a spec or hand-written? What endpoints do you document?
  • Guides and tutorials: What integration guides exist? Are they current?
  • Code examples: What languages and frameworks do you use?
  • SDK documentation: Do you have separate documentation for each SDK?
  • Changelog: Do you maintain a changelog or release notes?
  • Metadata: Do you have metadata for your content like dates, authors, and tags?

​
Export your existing content

  • Export to Markdown for the simplest migration to Mintlify.
  • Export OpenAPI specs for API reference content.
  • Export to HTML if Markdown isn’t available, then convert to Markdown.

​
Plan your documentation structure

Developer documentation typically includes several content types. Structure your navigation around how your users understand your product.
docs.json example
{
  "navigation": {
    "groups": [
      {
        "group": "Get Started",
        "pages": [
          "introduction",
          "quickstart",
          "authentication"
        ]
      },
      {
        "group": "Guides",
        "pages": [
          "guides/webhooks",
          "guides/error-handling",
          "guides/rate-limits",
          "guides/pagination"
        ]
      },
      {
        "group": "API Reference",
        "pages": [
          "api-reference/overview",
          "api-reference/users",
          "api-reference/orders",
          "api-reference/products"
        ]
      },
      {
        "group": "SDKs",
        "pages": [
          "sdks/javascript",
          "sdks/python",
          "sdks/go"
        ]
      }
    ]
  }
}
See Navigation for more configuration options.

​
Set up your API reference

If you have an API, generate an interactive reference from your OpenAPI specification.
1

Add your OpenAPI spec

Add your OpenAPI specification file to your project. You can use YAML or JSON format.
your-project/
├── docs.json
├── openapi.yaml
└── api-reference/
    └── overview.mdx
2

Configure the spec in docs.json

Reference your OpenAPI file in your docs.json configuration.
Configuration example
{
  "openapi": "openapi.yaml"
}
3

Add endpoints to navigation

Add the endpoints to your docs.json navigation. See OpenAPI setup for configuration options.
Navigation example
{
  "group": "API Reference",
  "pages": [
    "api-reference/overview",
    "api-reference/users/list-users",
    "api-reference/users/get-user",
    "api-reference/users/create-user"
  ]
}

​
Set up the assistant

The assistant helps developers find answers and understand code examples. Configure it from your dashboard.
  • Sample questions: Add developer-focused questions like “How do I authenticate API requests?” or “Show me how to handle webhooks.”
  • Code explanations: The assistant can explain code blocks in context when developers ask questions about specific examples.

​
Set up versioning

If you maintain multiple API versions, configure versioning so developers find documentation for their version.
Versioning example
{
  "versions": ["v2", "v1"],
  "navigation": {
    "groups": [
      {
        "group": "API Reference",
        "version": "v2",
        "pages": ["v2/api-reference/users"]
      },
      {
        "group": "API Reference",
        "version": "v1",
        "pages": ["v1/api-reference/users"]
      }
    ]
  }
}
See Versions for more information.

​
Connect to your repository

Install the Mintlify GitHub App to keep documentation in sync with your codebase and enable contributions.
1

Connect your repository

Link your GitHub repository in the dashboard. This enables automatic deployments when you push changes.
2

Configure branch settings

Set your production branch and enable preview deployments for pull requests. This lets you review documentation changes before they go live.
If you use GitLab, see GitLab for configuration instructions.

​
Maintain your documentation

Developer documentation needs regular updates so that information is accurate and usable.
1

Keep the API reference current

Update your OpenAPI specification whenever you release changes. If your specification is generated from code, automate this in your release process.
2

Update code examples

Review code examples when you release new SDK versions or product updates. Outdated examples cause integration failures and support requests.
3

Maintain a changelog

Document breaking changes, new features, and deprecations. Developers rely on changelogs to understand what changed between versions. See Changelogs for more information.
4

Monitor feedback

Review assistant conversations and search analytics to identify gaps in your documentation. If developers repeatedly ask about the same topic, improve that section. See Maintenance for more information.

​
Next steps

Your developer documentation is ready to launch. After deploying:
  1. Announce the documentation to your developer community.
  2. Monitor search patterns and assistant conversations for gaps.
  3. Set up a process to update docs with each API release.
  4. Gather feedback from developers to improve content over time.