Mintlify Convert
Convert MDX documentation to Mintlify format with enhanced features for seamless migration.
✨ Features
🎯 Core Conversions
- ✅ Frontmatter generation (title, description, icon, mode)
- ✅ Callouts/Admonitions → Proper Mintlify components (
<Warning>,<Tip>,<Note>,<Info>,<Check>) - ✅ Numbered lists → one
<Steps>per list, with plain-text titles taken from each step - ✅ Help sections →
<Card>components with contextual icons - ✅ API links → Mintlify API reference format
- ✅ Code blocks with proper formatting
🧩 Advanced Components (Enhanced with Technical Writing Rules)
- ✅
<Accordion>for H3 sections whose titles match a keyword heuristic (troubleshooting, FAQ, advanced, common issues, known issues, error codes, walkthrough, step by step, breakdown) - ✅
<Tabs>and<Tab>for language-labelled code blocks, with display names such as "JavaScript" - ✅
<Banner>for paragraphs that start with "Deprecated:", "Important:", "Notice:" or "Alert:" - ✅
<Frame>around images that are copied with--download-assets
🧭 Navigation
- ✅
docs.jsongeneration (default), or legacymint.jsonwith--legacy-mint-json - ✅ Nested groups based on folder structure ("Getting Started" first, then "Documentation", then A-Z)
- ✅ Proper page titles from frontmatter
- ✅ Optional alphabetical sorting
🖼️ Asset Handling
- ✅ Image copying to
/imagesdirectory (only with--download-assets, only from inside the input directory) - ✅ Relative link rewriting (links that resolve outside the input directory are left unchanged)
- ✅ Automatic path correction
🔧 Quality Assurance
- ✅ Input files over 1 MiB are rejected; symlinked inputs and
file:images are skipped with a warning on stderr - ✅ MDX validation (unclosed or mismatched tags; code blocks are ignored)
- ✅ Detailed error reporting
- ✅ Verbose mode for debugging
🚀 Quick Start
Installation
# From source (Python 3.10 or newer)
git clone https://github.com/Olamideod/mintlify-convert.git
cd mintlify-convert
pip install -e .
The package is not yet published to PyPI.
Basic Usage
# Convert a single file
mintlify-convert input.mdx -o output.mdx
# Convert an entire directory
mintlify-convert docs/ -o mintlify-docs/
# With all features
mintlify-convert docs/ -o mintlify-docs/ \
--generate-config \
--download-assets \
--validate \
--sort-pages
--generate-config writes docs.json. Add --legacy-mint-json to write mint.json instead. --generate-mint-json is a deprecated alias for both flags together.
Converting is idempotent: running the tool on its own output produces the same output. The output path must not be the same as, or inside, the input path.
📖 Documentation
- Getting Started - Quick start guide
- API Reference - Complete CLI and programmatic API
- Component Mapping - How patterns are converted
- Troubleshooting - Common issues and solutions
🎯 Component Conversions
Callouts (Enhanced)
Input:
> **Warning:** This is a critical note.
> Please read carefully.
Output:
<Warning>
**Warning:** This is a critical note.
Please read carefully.
</Warning>
Steps (Enhanced with Smart Titles)
Input:
1. Install dependencies using npm
2. Configure your environment variables
3. Start the development server
Output:
<Steps>
<Step title="Install dependencies using npm">
Install dependencies using npm
</Step>
<Step title="Configure your environment variables">
Configure your environment variables
</Step>
<Step title="Start the development server">
Start the development server
</Step>
</Steps>
Tabs (Enhanced Language Support)
Input:
JavaScript:
const api = require('api');
Python:
import api
Output:
<Tabs>
<Tab title="JavaScript">
```javascript
const api = require('api');
```
</Tab>
<Tab title="Python">
```python
import api
```
</Tab>
</Tabs>
Development
Setup
git clone https://github.com/Olamideod/mintlify-convert.git
cd mintlify-convert
pip install -e ".[dev]"
Run Tests
pytest tests/ -v --cov=mintlify_convert
Run Mintlify Convert
# Convert all MDX files in docs/ and write docs.json
python -m mintlify_convert.cli docs/ -o mintlify-docs/ --generate-config
# Convert a single file
python -m mintlify_convert.cli doc.mdx -o output.mdx
Conversion behaviour
The converter follows the component guidance in agent.md:
- Callouts become
<Warning>,<Tip>,<Note>,<Info>or<Check> - Numbered lists become
<Steps>with descriptive titles taken from each step - Accordions, Banners and Frames follow the narrow rules listed under Features
- Callouts, banners and numbered lists that start with a code fence are left unconverted; banners and help cards only match at the start of a paragraph
- Three or more consecutive language-labelled blocks form one
<Tabs>group - Code fences are left untouched
Code Formatting
black mintlify_convert/
flake8 mintlify_convert/
mypy mintlify_convert/
Project Structure
mintlify-convert/
├── mintlify_convert/ # Main package
│ ├── __init__.py # Package initialization
│ ├── cli.py # Command-line interface
│ ├── converter.py # Core conversion logic
│ ├── navigation.py # docs.json / mint.json generation
│ └── utils.py # Helper utilities
│
├── tests/ # Test suite
│ ├── test_converter.py # Unit tests for converter
│ ├── test_integration.py # Integration tests
│ ├── test_navigation.py # Navigation tests
│ └── fixtures/ # Test fixtures
│
├── examples/ # Example conversions
│ ├── basic/ # Basic examples
│ ├── advanced/ # Advanced examples
│ └── full-migration/ # Complete migration example
│
├── docs/ # Package documentation
│ ├── getting-started.mdx
│ ├── api-reference.mdx
│ ├── component-mapping.mdx
│ └── troubleshooting.mdx
│
├── .github/
│ └── workflows/ # CI/CD workflows
│
├── pyproject.toml # Modern Python project config
├── requirements.txt # Dependencies
├── requirements-dev.txt # Development dependencies
├── README.md # This file
├── LICENSE # MIT License
├── CHANGELOG.md # Version history
├── agent.md # Mintlify technical writing rules
└── .gitignore # Git ignore rules
🗺️ Roadmap
Future work
- AI-powered description generation (not implemented)
- Parallel processing for large docs (not implemented)
- Interactive migration wizard (TUI)
- Incremental conversion (only changed files)
- Custom component plugins
- Automatic image optimization
- Diff viewer for conversions
- VS Code extension
- Web-based converter UI
- Support for Docusaurus → Mintlify
- Support for GitBook → Mintlify
- Migration analytics and reporting
🤝 Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📄 License
MIT License - see LICENSE file for details.
Support
- Issues: GitHub Issues
🙏 Acknowledgments
Built with ❤️ to help teams migrate to Mintlify faster.
Star ⭐ this repo if it helped you!
Metadata
Release files for mintlify-convert 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mintlify_convert-2.0.0.tar.gz | 48.5 kB | With provenance | Details for mintlify_convert-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mintlify_convert-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for mintlify_convert-2.0.0-py3-none-any.whl |
Total release size: 74.6 kB
Release files / mintlify_convert-2.0.0.tar.gz
| Download URL | mintlify_convert-2.0.0.tar.gz |
|---|---|
| Size | 48.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
179a239947d7a4b5f204c594e542ecb5fea99e629b22f8d136de709bdf8f9e3b
|
|
BLAKE2b-256 checksum How to use checksums |
1cb42732c51f614a9692fa1d18d2eee63b7aa14b531e7f4512a28764525a0765
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / mintlify_convert-2.0.0-py3-none-any.whl
| Download URL | mintlify_convert-2.0.0-py3-none-any.whl |
|---|---|
| Size | 26.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
12bd71f3a452050a06d273df4d52a649ddb1d947d6d9453cde0f2fd89b5b3619
|
|
BLAKE2b-256 checksum How to use checksums |
1013f4d41790ea6bf08da83916fa81945d3c3d0439c4ff3e1d87ea7bb1c0ea98
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logSecurity for mintlify-convert 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mintlify_convert-2.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.