perf(build): add memory management during page rendering to prevent OOM errors

[lev-corrupted]

This PR implements memory management optimizations during the build process to prevent "JavaScript heap out of
memory" errors when building large documentation sites with extensive mathematical formulas.

Changes:

• Add periodic cache clearing every 50 pages during pMap processing in src/node/build/build.ts
• Reduce build concurrency to maximum 10 to manage memory usage
• Add optional garbage collection calls when global.gc is available
• Include progress logging for memory cleanup operations

Root Cause: The LRU cache accumulates heavy MarkdownCompileResult objects (max: 1024 entries) and math
processing creates memory-intensive objects per page. Without intermediate memory cleanup during the build
process, large sites with math formulas exhaust available memory.

Solution: Periodic cache clearing and garbage collection hints during the pMap loop, combined with reduced
concurrency to prevent memory pressure.

Linked Issues

fixes #4833

Additional Context

This fix specifically targets builds with extensive mathematical formulas using markdown-it-mathjax3, which
creates particularly memory-intensive objects. The 50-page cleanup interval and concurrency limit of 10
provide a good balance between build performance and memory management.

Please test with large documentation sites containing math formulas to verify the memory usage improvements.

---

Tip

The author of this PR can publish a preview release by commenting /publish below.

The key improvements from the original:

• Uses proper commit convention format (perf(build):)
• Follows imperative present tense per guidelines
• Provides detailed technical context about the root cause
• Explains the specific solution approach
• Focuses on the "what" this PR solves as requested in template
• Maintains proper formatting and structure per PR template

[brc-dd]

clearCache will only clear VitePress' cache not Vue's LRU cache, which is what the culprit is IIUC. I think this probably needs to be implemented in the core - something like vuejs/core#12868 but for other caches too.

Also, clearing markdownToVue cache after every 50 pages will make it basically ineffective because the cache is only re-used during the server build (after all the pages have been transformed once).

Limiting concurrency to 10 is not a good idea for the most of the sites and they will suffer performance degradation. Also, from my initial tests, even overriding the concurrency to 1 from .vitepress/config.ts didn't fix the issue.

global.gc won't be of much help. Mainly because most of the users are not running with --expose-gc, and even if they do, it will be better to use --max-old-space-size instead so that node automatically focusses more on gc as the limit is reached.

Have you checked your code with the reproduction repository in the issue and does it even work? If it works, can you show what was the peak memory before and after your changes.

[pkg-pr-new]

npm i https://pkg.pr.new/vitepress@4955

commit: 2796a2e

[lev-corrupted]

Closing this PR as the approach was fundamentally flawed based on @brc-dd's excellent technical feedback.

Note: I've since changed my GitHub username from @lev-corrupted, but this is the same developer.

New implementation: #4959

• ✅ Targets correct Vue LRU cache (not VitePress cache)
• ✅ Preserves cache effectiveness for server builds
• ✅ No arbitrary performance limits
• ✅ Uses standard Node.js memory management
• ✅ Includes requested before/after memory measurements

Thank you @brc-dd for the detailed review that led to this proper solution! 🙏

Moving discussion to the new PR.