Mintlify Setup & Migration Guide for API Portals

Transitioning to a modern documentation stack requires aligning with established Developer Portal Frameworks & UI Setup standards before executing the migration. This blueprint details initialization, spec integration, and CI automation workflows required to deploy Mintlify at scale. The process preserves developer experience and routing integrity throughout the transition.

Key objectives:

Initialize project structure with version-controlled mint.json
Map legacy endpoints to Mintlify’s OpenAPI routing engine
Configure GitHub Actions for automated preview deployments
Implement redirect rules for zero-downtime migration

Project Initialization & Directory Structure

Establish the foundational configuration and file hierarchy required for Mintlify’s static site generator. Run npx mintlify init to scaffold the baseline directory structure. Define navigation trees and metadata schemas in mint.json to control routing precedence. Apply theme overrides and typography tokens via theme.css to match brand guidelines. Validate local server compatibility by executing npx mintlify dev.

Required configuration files: mint.json, package.json, theme.css

OpenAPI Spec Integration & Routing

Ensure seamless API reference rendering by validating spec compatibility. Align with Redocly & OpenAPI UI Configuration best practices for schema mapping and validation. Link OpenAPI 3.0/3.1 YAML or JSON files directly to navigation nodes in mint.json. Configure code sample generation for target languages using the openapi block. Set up webhook triggers to auto-rebuild on spec repository updates.

Required configuration files: mint.json, openapi.yaml, ci-scripts/validate-spec.js

CI/CD Pipeline & Automated Builds

Automate build validation and deployment while preserving legacy routing structures. Maintain continuity with patterns previously managed via Swagger UI Customization workflows. Implement a GitHub Actions workflow to generate ephemeral PR previews on every pull request. Cache node_modules and Mintlify build artifacts to reduce pipeline execution time. Execute link validation and broken route detection as a pre-deploy gate.

Required configuration files: .github/workflows/docs-deploy.yml, mintlify.config.json

Legacy Content Migration & Redirect Mapping

Execute structured content transfer while maintaining SEO equity and developer bookmark integrity. Map legacy URL patterns to new Mintlify routes using a structured CSV audit. Generate 301 redirect arrays directly in mint.json to prevent 404 errors. Audit and convert legacy Markdown syntax to MDX, ensuring component compatibility. Verify search indexing and metadata preservation before final cutover.

Required configuration files: mint.json, redirects.csv, migration-scripts/convert-mdx.py

Configuration Reference

Core `mint.json` Configuration

{
 "name": "API Portal",
 "logo": "/logo.svg",
 "favicon": "/favicon.svg",
 "colors": { "primary": "#0052FF", "light": "#E0E7FF", "dark": "#001A4D" },
 "navigation": [
 { "group": "API Reference", "pages": ["reference/openapi"] }
 ],
 "openapi": "/reference/openapi.yaml",
 "redirects": [
 { "source": "/v1/docs/:path*", "destination": "/reference/:path*", "permanent": true }
 ]
}

Context: Defines routing, theming, and OpenAPI spec binding while establishing permanent redirects for legacy paths. Expected Output: Mintlify CLI parses this file to generate the navigation tree and mount the OpenAPI reference at /reference/openapi.

GitHub Actions Workflow

name: Deploy Docs
on:
 push:
 branches: [main]
 pull_request:
 branches: [main]
jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - uses: actions/setup-node@v4
 with:
 node-version: '20'
 - run: npm ci
 - run: npx mintlify validate
 - run: npx mintlify build

Context: Triggers on PRs and main branch pushes, installs dependencies, validates the OpenAPI spec, and executes a production build. Expected Output: Pipeline exits with 0 on success, generating a deployable static artifact ready for CDN distribution.

Common Pitfalls

OpenAPI Spec Version Mismatch

Mintlify strictly requires OpenAPI 3.0.x or 3.1.x. Legacy Swagger 2.0 specs will fail validation and break reference generation. Convert legacy specs using openapi-cli before integration.

Broken Internal Links Post-Migration

Relative Markdown links often break when migrating from flat directory structures to Mintlify’s nested navigation model. Use absolute paths or configure redirect arrays. Run mintlify broken-links locally to catch failures early.

CI Build Cache Conflicts

Aggressive caching of node_modules or Mintlify’s build artifacts can cause stale theme overrides or outdated spec snapshots in preview environments. Invalidate caches when mint.json or openapi.yaml changes. Add explicit cache keys to your workflow if artifacts diverge unexpectedly.