Performance issues

Diagnose slow builds, slow page loads, and other performance problems in Mintlify.

Performance problems in Mintlify fall into two categories: slow build times and slow page loads. The fixes are different for each.

Slow builds

If your deployments are taking longer than expected, common causes include:

Large images — Unoptimized images dramatically slow builds. Compress images before adding them to your repository, or host them externally (Cloudinary, S3) and reference them by URL.

Many pages — Sites with thousands of pages take longer to build. This is usually not a problem until you reach 2,000+ pages.

External data fetching — If your docs fetch data from external APIs at build time, slow API responses extend build times. Cache responses or use static data where possible.

Check your build time trend

Go to [Project] → Deployments and look at the build duration column. If build times have increased gradually, it’s likely due to content growth. A sudden jump suggests a recently added page or image is the culprit.

Slow page loads

If your docs pages load slowly for readers, common causes include:

Large images on the page — Audit your pages for large embedded images. Use smaller images or reference external images so they load from a CDN rather than your repository.

Custom JavaScript — Scripts added via Google Tag Manager or custom <script> tags can significantly slow page loads if they’re not performance-optimized.

CDN propagation — After a new deployment, CDN caches need time to propagate globally. Pages may load slightly slower for 5–10 minutes after a deploy.

Checking your build performance

Use the Mintlify CLI to validate your docs locally:

mintlify dev

The local dev server shows warnings for pages with issues (large images, invalid components) that could affect build or load performance.

Reporting a performance issue

If you’ve ruled out the common causes and pages are still loading slowly, contact support and include:

• Your project URL.
• A specific page URL that loads slowly.
• A screenshot of the network panel in browser dev tools showing load times.