Skip to main content

​
Documentation Versioning

This document explains how versioned documentation works for tif1.

​
Overview

The tif1 documentation uses Mintlify’s free plan with a separate branch deployment strategy. Documentation is automatically deployed when releases are published.

​
Deployment Strategy (Free Plan)

Since we’re on Mintlify’s free plan (no API access), we use a branch-based deployment:
  1. Development: All doc changes happen on the main branch
  2. Production: Mintlify auto-deploys from the docs-production branch
  3. Trigger: GitHub Actions pushes to docs-production only on releases

​
Why This Approach?

  • Free plan limitation: No API key for programmatic deployment
  • Solution: Use Mintlify’s auto-deploy feature with a dedicated branch
  • Benefit: Docs only update on releases, not every commit

​
How It Works

​
On Release

  1. You publish a new release (e.g., v0.2.0)
  2. GitHub Actions workflow triggers
  3. Workflow updates docs.json with the new version
  4. Workflow pushes docs to docs-production branch
  5. Mintlify auto-deploys within minutes
  6. Version appears in the version selector

​
Version Selector

Users can switch between documentation versions using the version selector in the navbar:
  • Each release creates a versioned snapshot
  • Versions are listed in the versions array in docs.json
  • The version field shows the currently deployed version

​
Mintlify Configuration

In your Mintlify dashboard, configure:
  1. Git Settings:
    • Repository: TracingInsights/tif1
    • Branch: docs-production (important!)
    • Subdirectory: docs
  2. Auto-Deploy:
    • Enable auto-deploy
    • Mintlify watches docs-production for changes

​
Manual Deployment

To deploy docs without creating a release:
  1. Go to GitHub Actions
  2. Select “Deploy Documentation” workflow
  3. Click “Run workflow”
  4. Enter the version (e.g., v0.1.0)
  5. Click “Run workflow”
This is useful for:
  • Fixing documentation bugs between releases
  • Updating docs for an existing version
  • Testing the deployment process

​
Version Management

​
Automatic Updates

The GitHub Actions workflow automatically:
  • Extracts version from release tag (e.g., v0.2.0 → 0.2.0)
  • Updates the version field in docs.json
  • Adds the version to the versions array (if not present)
  • Commits and pushes to docs-production

​
Manual Updates

If you need to manually manage versions: 
# Edit docs/docs.json
{
  "version": "0.2.0",
  "versions": ["latest", "0.2.0", "0.1.0"]
}

​
Best Practices

  1. Always test locally before merging doc changes: 
    cd docs
npx mintlify dev
  2. Keep versions in sync: The workflow handles this, but verify after deployment
  3. Use semantic versioning: Match your package versions (e.g., 0.1.0, 0.2.0)
  4. Don’t push to docs-production directly: Always use the GitHub Actions workflow
  5. Review the PR preview: The docs-preview workflow validates changes

​
Troubleshooting

​
Docs Not Deploying

  • Check Mintlify dashboard → Git Settings → Branch is docs-production
  • Verify auto-deploy is enabled
  • Check GitHub Actions logs for errors
  • Ensure docs-production branch exists and has recent commits

​
Version Selector Not Showing

  • Verify versionSelector.enabled: true in docs.json
  • Check that versions array has multiple entries
  • Clear browser cache and reload

​
Deployment Delayed

  • Mintlify auto-deploy can take 2-5 minutes
  • Check Mintlify dashboard for deployment status
  • Verify webhook is configured (if applicable)

​
Migration from API-Based Deployment

If you later upgrade to a Pro plan:
  1. Update .github/workflows/docs.yml to use Mintlify CLI
  2. Add MINTLIFY_API_KEY to GitHub Secrets
  3. Change deployment branch back to main in Mintlify settings
  4. Remove the docs-production branch strategy

​
Resources

Last modified on March 13, 2026