Build Failing in CI Due to Memory Issues (~14k MD files) – Works Locally

[TaushifAli1]

Hi everyone,

We’re running into memory issues when building our Docusaurus site in CI and would appreciate some guidance.

Context

• Docusaurus version: 3.8.1
  -Node version: 22
  -Docs size: ~14,000 markdown files
• Build output size (local): ~805 MB
• CI environment: Our own GitHub runner with 32 GB RAM
• experimental_faster: enabled

Problem

The build works fine locally, but it fails in GitHub Actions due to memory issues.

We are using our own runner with 32 GB RAM, so we were not expecting memory to be a bottleneck.
What We’ve Tried

1. Increased Node heap:
   node --max-old-space-size=16384

Still failing. Given that the runner has 32 GB RAM, we suspect this might not be the real issue.

2.Added swap space in CI:
pierotofy/set-swap-space

This does allow the build to succeed.
However:

• This feels like a temporary workaround.
• With continued content growth, this likely won’t scale.

We did memory analysis, we are seeing ram is eaten up during docusaurus build (this is without swap space)

[slorber]

Hey 👋

It's impossible to help with this kind of issue without knowing more about your site and having access to its source.

Set DOCUSAURUS_PERF_LOGGER=true to see what takes time, locally and on GitHub, then share with us the full log.

Why do you have 14k md files? Are they written manually or codegen?

We have recently found out that codegen of large mdx documents can be a huge problem for performance. An OpenAPI plugin changed its strategy and became much faster. #11664