Skip to main content

Mintlify Convert

License: MIT

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.json generation (default), or legacy mint.json with --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 /images directory (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

🎯 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:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

Support

🙏 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)

Source distribution for mintlify-convert 2.0.0
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)

Table of built distributions (wheels) for mintlify-convert 2.0.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

2.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page