We rebuilt Cloudflare's developer documentation - here's what we learned

A content-heavy docs site moves from Gatsby to Hugo

Cloudflare recently shipped a new version of developers.cloudflare.com, the company's developer documentation site. The update involved replacing the underlying documentation engine, migrating from Gatsby to Hugo, and consolidating what had been dozens of separate Workers Sites into a single Cloudflare Pages instance. The result: faster builds, an easier local development experience, and 90% less JavaScript shipped to visitors.

Why the engine changed

Cloudflare's developer docs, hosted open source on GitHub, currently comprise 1,600 pages that have absorbed roughly 4,000 pull requests from internal staff and community contributors. The engine behind those pages has been rebuilt several times over the years, most recently in mid-2020 with a custom docs engine that brought dark mode, proper syntax highlighting, and a unified framework for all of Cloudflare's product documentation.

That setup worked initially, but within eighteen months and thousands of PRs, architectural problems surfaced. The site was rendered client-side, which carried performance costs for readers on lower-end devices. Deployment involved spinning up a separate Cloudflare Worker for each product's staging and production instances — over a hundred Workers that were constantly updated, making it difficult to trace failed deployments. And Gatsby, the static site generator of choice, proved to be a poor fit for a content-heavy documentation site. Its long dependency chains made local contribution setups painfully slow, and production builds could take nearly an hour to compile Markdown and images into HTML.

Hugo, written in Go, offered a compelling alternative. In early testing, Cloudflare found it could build the docs content in seconds. That performance difference was a primary driver for the rewrite.

Migration mechanics: from MDX to standard Markdown

The biggest technical hurdle wasn't the framework switch itself, but the content format. Cloudflare's docs were authored in MDX, Gatsby's Markdown extension that allows React components to be embedded in pages. MDX isn't CommonMark-compliant, and its permissive syntax doesn't translate cleanly to Hugo or any other standards-based Markdown processor. Every one of the 1,600 pages had to be converted to stricter, more standard Markdown.

The migration team also had to avoid blocking the repository's ongoing update cycle. Thousands of changes were landing via PRs, and a prolonged migration would have caused merge conflicts and stalled deployments. The solution was automation. Cloudflare built a migration script that applied all necessary changes in a single coordinated pass on the morning of release, orchestrating the series of Node scripts and git commands through a Makefile — reducing the entire operation to a single make run command.

The script worked by parsing file contents into an abstract syntax tree (AST) using MDX-compatible utilities, then traversing that tree to modify nodes. For instance, heading and anchor nodes were checked to ensure primary headers and internal links were consistent. After the traversal, a stringifier function converted the modified AST objects back into Markdown text. An abbreviated example of this approach, using mdast-util-from-markdown, mdast-util-to-markdown, and the traversal library astray, is available on GitHub.

The migration also provided an opportunity to clean up code snippets throughout the docs. Thousands of code examples were run through a Prettier-based formatter script, which enforced a consistent code style and surfaced syntax errors in JavaScript, TypeScript, Rust, JSON, and C++. Those errors were manual fixed, and the formatter was added to CI to catch invalid code in future contributions.

When the automated migration ran, it applied over one million changes across close to 5,000 files in under two minutes. The resulting PR was reviewed with product owners, with fine-tuning applied afterward.

One project instead of 48

The previous Workers Sites architecture treated each product's documentation as an individual site, managed behind an umbrella Worker on developers.cloudflare.com. That served production well but made local development cumbersome. The Hugo migration collapsed 48 moving parts into a single project, with one build command and one deployable unit.

That consolidation opened the door to moving the docs to Cloudflare Pages. GitHub PRs now automatically generate preview deployments, and commits to the production branch queue live site updates. Contributors get a local development workflow that mirrors production behavior exactly.

The outcome: HTML-first docs

The redesign produced a site that looks nearly identical to its predecessor but behaves very differently under the hood. The benefits fall into three categories:

• Simpler architecture: fewer moving parts for both development and deployment, making it easier for new contributors and team members to get up to speed.
• Faster iteration: local dev flow is snappier and replicates production faithfully, increasing both development speed and confidence in changes.
• Less client-side work: the site is now HTML-first, shipping 90% fewer JavaScript bytes and leaving visitors' browsers with less to process.

The reduced JavaScript payload has real performance consequences. Page speed is a factor in Google's search ranking, and Cloudflare's Lighthouse performance score improved significantly after the migration. The SEO score, which measures a crawler's ability to parse page metadata, stayed the same — the underlying content and metadata weren't changed.

What's next for docs development

The new engine gives Cloudflare's content team faster validation capabilities. Local builds are instant, and Cloudflare Pages preview links give product managers and engineers a quick way to review docs as they would appear in production.

Future plans include adding spell checking, automated link validation, and visual diff tools to the review pipeline. The documentation project remains fully open source on GitHub, and Cloudflare continues to accept suggestions and feedback from readers.