Documentation Versioning
This document explains how the tif1 documentation is deployed and how it relates to package releases.Overview
The documentation runs on the Mintlify free plan and uses a separate branch deployment strategy. One documentation version is live at a time, and it describes the latest published release.Deployment Strategy (Free Plan)
The Mintlify free plan has no API access. Deployment uses a dedicated branch:- Development: All doc changes happen on the
mainbranch - Production: Mintlify auto-deploys from the
docs-productionbranch - Trigger: GitHub Actions pushes to
docs-productiononly on releases
Reason for 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
- The owner publishes a new release (for example,
v0.8.0) - The “Deploy Documentation” workflow (
.github/workflows/docs.yml) triggers - The workflow copies
docs/from the release commit to thedocs-productionbranch - Mintlify auto-deploys within minutes
One Live Version
The site has no version selector.docs.json does not declare versions: Mintlify’s navigation.versions needs one navigation tree per version, and the project keeps a single tree that always documents the latest release. Readers who need the documentation for an older release can browse the docs/ directory of that release tag on GitHub.
Mintlify Configuration
In the Mintlify dashboard, configure:-
Git Settings:
- Repository:
TracingInsights/tif1 - Branch:
docs-production(important!) - Subdirectory:
docs
- Repository:
-
Auto-Deploy:
- Enable auto-deploy
- Mintlify watches
docs-productionfor changes
Manual Deployment
To deploy docs without creating a release:- Go to GitHub Actions
- Select “Deploy Documentation” workflow
- Click “Run workflow”
- Enter the version (for example,
v0.8.0); it is only used in the commit message - Click “Run workflow”
- Fixing documentation bugs between releases
- Testing the deployment process
Best Practices
-
Always test locally before merging doc changes:
-
Validate before merging: run
npx mint validateandnpx mint broken-linksindocs/, and runuv run python tools/run_doc_examples.pyfrom the repository root to execute the code blocks - Match the package: when a release changes the public API, update the pages in the same pull request. Then the deployed docs match the released package
- Do not push to docs-production directly: Always use the GitHub Actions workflow
- 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-productionbranch exists and has recent commits
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
To move to a Pro plan later:- Update
.github/workflows/docs.ymlto use the Mintlify CLI - Add
MINTLIFY_API_KEYto GitHub Secrets - Change deployment branch back to
mainin Mintlify settings - Remove the
docs-productionbranch strategy