Fixing Slow Astro Builds Caused by Large MDX Collections

A documentation site migrated to Astro with every page as MDX "in case we need components" builds quickly at 200 pages and slowly at 4,000. The build log shows the time disappearing into two phases — building static entrypoints and generating static routes — and the CI bill shows it too. The cause is usually not Astro itself but what MDX asks it to do: every .mdx file becomes a JavaScript module that Vite must compile and bundle, and every page then executes that module to render. Plain Markdown skips both.

This guide fixes a slow build on a 4,200-page product documentation site built with Astro 5.2 and Starlight, where a cold CI build had grown to 11 minutes 40 seconds. It shows how to measure where the time goes, which pages actually need MDX, and the four changes that brought the build to 3 minutes 50 seconds. It sits under Astro vs Eleventy for Documentation Sites.

Symptoms

Warm builds barely beat cold ones, which showed that caching was not working either.

Step 1: Measure Per-File Cost

Copy 200 representative pages into a scratch project twice: once as .mdx, once renamed to .md (only for pages without components). Then time both with hyperfine:

hyperfine --warmup 1 --runs 5 'npx astro build --root bench-mdx' 'npx astro build --root bench-md'

At 4,200 pages, that difference alone accounts for about 11 minutes of serial work; parallelism on 4 cores brings it down, but the ratio holds.

Step 2: Find the Pages That Actually Use Components

A script lists every MDX file that contains an import statement or a capitalised JSX tag outside code fences:

import { glob } from 'glob';
import fs from 'node:fs/promises';
const files = await glob('src/content/docs/**/*.mdx');
const plain = [];
for (const f of files) {
  const body = (await fs.readFile(f, 'utf8')).replace(/```[\s\S]*?```/g, '');
  if (!/^import\s/m.test(body) && !/<[A-Z][A-Za-z]*[\s/>]/.test(body)) plain.push(f);
}
console.log(`${plain.length} of ${files.length} MDX files use no components`);

The answer was 3,270 of 4,200 — 78% of pages paid MDX's cost for nothing. Most of the remaining 930 used one of three components: <Tabs>, <Aside> and a custom <ApiParam>.

Step 3: Convert Plain Pages and Use Directives for Asides

Renaming the 3,270 files to .md was mechanical. Two details needed care:

• MDX-only syntax in plain files. A few used {/* comments */} or escaped braces; the script converted comments to HTML comments and unescaped braces.
• Asides. Starlight supports :::note and :::caution directive syntax in Markdown, which renders the same component as <Aside>. Converting 610 pages whose only component was <Aside> moved them to Markdown too.

That left 320 pages in MDX — those using <Tabs> and <ApiParam> — and 3,880 in Markdown.

Step 4: Audit the remark and rehype Plugins

The site ran seven Markdown plugins. Timing a 200-page build with each one removed found one outlier: a remark plugin that validated external links by sending a HEAD request for every URL, with a 2-second timeout, on every build. It was responsible for 13 ms per page on average and occasional 2-second stalls. Link checking moved to a scheduled job, as in Crawling for Broken Links on a Schedule. The syntax highlighter was the next most expensive; Expressive Code's cost was acceptable, but two custom Shiki languages loaded from JSON files on every page were preloaded once at startup instead.

Step 5: Make the Content Layer Cache Survive CI

Warm builds were not faster because the CI workflow restored node_modules but not Astro's caches. The content layer stores parsed entries and digests in node_modules/.astro/data-store.json, and asset processing caches in node_modules/.astro/assets (or the configured cacheDir). Caching them keyed on the lockfile and Astro config:

- uses: actions/cache@v4
  with:
    path: |
      node_modules/.astro
      .astro
    key: astro-${{ hashFiles('package-lock.json', 'astro.config.mjs') }}-${{ github.sha }}
    restore-keys: astro-${{ hashFiles('package-lock.json', 'astro.config.mjs') }}-

With the cache restored, unchanged entries skip parsing and image transforms are reused. The content layer guide covers what the cache does and does not skip.

Measured Impact

Why MDX Costs More: What Happens Per File

It helps to know what the build is doing with each file, because it explains which changes help. A Markdown file in a content collection is parsed by remark, transformed by the remark and rehype plugins, and serialised to an HTML string; that string is stored and inserted into the layout at render time. An MDX file goes through the same remark and rehype stages, but its output is JavaScript: a module exporting a component, with an import for every component it uses. Vite then has to resolve those imports, transform and bundle the module along with the rest of the site's server code, and Astro has to execute the module to produce HTML for each page.

That pipeline gives MDX its power — components, expressions, imports — and it is also why its cost scales differently. Bundling time grows with the number of modules, and memory grows because every compiled module is held in the server bundle during rendering. The 6.1 GB peak on this site was mostly the server bundle with 4,200 page modules in it. After conversion, the bundle contained 320 page modules, and peak memory fell to 2.4 GB with no other change. Starlight and Astro handle mixed collections without any configuration, so the conversion needed no code changes beyond renaming files and fixing a few MDX-only constructs.

Keeping It Fast

Two guardrails stop the build drifting back. A lint rule rejects new .mdx files that use no components, with a message suggesting .md; writers who need a component later can rename the file in the same pull request. And the build-time tracking job fails a pull request that adds more than 10% to the median of the last 20 main-branch builds, so a slow plugin shows up in the pull request that adds it.

Pitfalls & Rollback

• Defaulting every page to MDX. Use MDX only where a component is used.
• Treating warm and cold builds as the same. If they are close, the cache is not being restored.
• Network calls in Markdown plugins. They make builds slow and flaky; move them to scheduled jobs.
• Converting files with MDX-only syntax blindly. Comments and braces need converting too.
• Rollback: renaming files back to .mdx restores the old behaviour page by page; nothing else depends on the extension.

Conclusion

Large Astro builds slow down when thousands of pages are MDX without needing to be, because each MDX file is compiled, bundled and executed. Converting the 78% of pages that used no components, moving simple asides to directive syntax, removing a network-bound plugin and restoring the content layer cache took the 4,200-page build from 11 minutes 40 seconds to 3 minutes 50 seconds.

FAQ

Why is MDX slower to build than Markdown in Astro?

Each MDX file is compiled to a JavaScript module, bundled by Vite and then executed to render the page, while plain Markdown is rendered directly to HTML by the remark pipeline. The compile, bundle and execute steps add per-file work and memory. In the measurements in this guide an MDX page took about four times as long as the same content as Markdown.

Can I keep MDX for some pages and use Markdown for the rest?

Yes. A content collection can contain both md and mdx files, and the same layout renders both. Converting only pages that use no components to Markdown keeps MDX where it adds value. On the site in this guide, 78 percent of MDX files used no components at all.

Do remark and rehype plugins slow down Astro builds?

They run once per file, so a slow plugin multiplies by the number of pages. Syntax highlighting and plugins that parse or fetch external resources are the most expensive. Profile with a build of a subset of pages with and without each plugin, and look for plugins doing network requests or heavy work that could be cached.

Does the Astro content layer cache help with MDX builds?

The content layer caches parsed entries and their data between builds when the cache directory is preserved, so unchanged files skip parsing. Rendering still happens for every page in a static build. Preserving node_modules/.astro and the data store between CI runs cut the warm build time by about a third in this guide.

Related

• Parent: Astro vs Eleventy for Documentation Sites — build performance as a selection criterion.
• MDX vs Markdoc for Docs Content — when components in content are worth it.
• Shortcodes vs Components for Docs Authors — the authoring side of the trade-off.
• Incremental Builds in Astro with the Content Layer — the cache restored in Step 5.
• Fixing Eleventy Out-of-Memory Errors on Large Collections — the equivalent problem in Eleventy.