Posted on 2024-09-17
At work, I use MDX for writing technical documentation. It's very flexible and pretty nice to write. However, MDX has a big problem: performance.
Recently we moved from using JS components that hide/show versioned documents based on the version selected to using file path-based versioning. This is far better for us as writers from both a maintanability and a writing perspective. However, it introduced a major new problem in that it increased our build time from 3:30 to around 8:30. For a lightweight static site, this is pretty awful.
From what I understand, the issue is that MDX basically compiles down to a combination of HTML and JS, where the entire document must be rendered as a React syntax tree to work correctly. As you can imagine, this is hugely wasteful when it comes to building your site. The build process takes a long time, with each page taking between 80-240ms depending on complexity.
If you compare this to Markdown, which takes only a handful of ms to build for each page, the difference is stark. Markdown is extremely efficient, but it lacks in flexibility. Writing Remark plugins sucks compared to Astro and outputting React (an unfortunate necessity of my job) is an unknown. I'd love to move our work to pure Markdown, but it's not possible right now.
I decided today to try benchmarking our MDX build against a comparable Markdoc build. The results were pretty stunning. Not only is Markdoc a nicer interface into most of our React components, it's also MUCH faster to build. On my local machine, I got the following build times for around 2000 files:
- MDX: 242.63s
- Markdoc: 51.9s
That's an enormous difference. Obviously, Markdown would still be the best path forwards, but until Astro releases a really solid way of writing Remark interfaces for Markdown, Markdoc might be our best solution...