Why Cloudflare rewrote its docs stack again

Cloudflare has long treated developer documentation as a product rather than a finishing touch. The company's developers.cloudflare.com site has been open source since its first release in 2020, and the underlying engine has gone through multiple generations. The latest migration — from Hugo to Astro and Starlight — was driven by scalability limits and rising maintenance costs in the contributor workflow.

The decision to stay open source was deliberate. Keeping both content and framework publicly accessible lets outside developers contribute fixes, learn how the docs are built and maintained, and feed improvements back into the broader ecosystem. That philosophy shaped the evaluation criteria for the new stack: any update had to preserve the features that had become core to the experience.

What the 2021 Hugo migration established

The 2021 rebuild introduced a custom documentation engine and several capabilities that were treated as non-negotiable requirements for any future migration:

  • Faster development flow: Local development replicated production behavior, and preview links via Cloudflare Pages let stakeholders review content before it shipped.
  • Custom components: The resources-by-selector shortcode allowed content to be referenced across the repository and opened the door to additional checks and automations.
  • Structured changelogs: YAML-based entries could be published to RSS feeds, the Developer Discord, and the docs themselves.
  • Better performance: An HTML-first approach and near-instant local builds cut page load times significantly.

These features became the baseline for evaluating whether a new stack was worth adopting.

Choosing Astro and Starlight

For the 2024 update, Cloudflare selected Astro and, by extension, JavaScript. The framework addressed several items on the team's wishlist:

  • Content organization: Better tagging and cross-referencing between related pages via content collections, with Markdown front matter validated by Zod schemas and JSON schema generation for editor Intellisense.
  • Extensibility: Support for community plugins such as starlight-image-zoom for lightbox functionality.
  • Development experience: Build-time type checking with astro check, plus syntax highlighting, diagnostic messages, and plugins for ESLint, Stylelint, and Prettier.
  • JavaScript/TypeScript alignment: Matching the docs framework to the languages most contributors already know lowers the barrier to participation.
  • CSS management: Tailwind and scoped styles simplified styling concerns.

Starlight, Astro's documentation theme, tipped the decision. Its component override system and plugin architecture let the team reuse built-in components and base styles rather than building everything from scratch.

Migrating without a content freeze

With dozens of pull requests merged daily, a week-long code freeze was not an option. The migration had to happen while the repository stayed live. The team leaned on abstract syntax trees (ASTs) rather than regular expressions, since ASTs parse Markdown structure without tripping over whitespace and indentation details.

One concrete challenge was code block configuration. The Hugo-based site stored options like titles and line highlights in front matter inside the code block:

---
title: index.js
highlight: 1
---
const foo = "bar";

Starlight uses Expressive Code, where those options live on the opening code fence instead:

js title="index.js" {1}
const foo = "bar";

The team used astray, a utility for walking Markdown ASTs that was originally written for the 2021 migration. The transformation was straightforward:

  1. Parse node.value with the front-matter package.
  2. Assign the parsed attributes to node.meta.
  3. Replace node.value with the remaining code block content.
import { fromMarkdown } from "mdast-util-from-markdown";
import { toMarkdown } from "mdast-util-to-markdown";
 
import * as astray from "astray";
import type * as MDAST from "mdast";
import fm from "front-matter";
 
const markdown = await Bun.file("example.md").text();
 
const AST = fromMarkdown(markdown);
 
astray.walk<MDAST.Root, void, any>(AST, {
    code(node: MDAST.Code) {
        const { attributes, body } = fm(node.value);
        const { title, highlight } = attributes;
 
        if (title) {
            node.meta = `title="${title}"`;
        }
 
        if (highlight) {
            node.meta += ` {${highlight}}`;
        }
 
        node.value = body;
 
        return;
    }
})

Scale and effort

Compared to the 2021 migration — roughly 4,850 files changed and close to three weeks from planning to implementation — this one was nearly twice as large. The Astro migration touched 8,060 files and took six weeks total:

  • 10 days: Evaluate platforms, vendors, and features
  • 14 days: Migrate the components required by the documentation site
  • 5 days: Staging and user acceptance testing
  • 8 hours: Code freeze and the actual migration pull request

Net, the change removed 19,624 lines of code from the project's maintenance burden.

GitHub image of migrated PR

Lessons from the rollout

Involving Cloudflare Community MVPs during the planning and review phases proved valuable — their feedback shaped the approach before the switch. The tight preparation paid off: only one day of code freeze was needed, there were no rollbacks or major incidents, and visitors never saw downtime.

During testing, the team hit cases that warranted experimental Astro APIs. The documentation for those APIs was solid, thanks to the Astro community's open source work, and Cloudflare implemented them without slipping the release timeline.

An edge case did surface with build time performance: the site has more than 4,000 pages, and Starlight initially struggled. The Astro team triaged the issue quickly and began working on a permanent fix. That responsiveness reinforced the value of building on an actively maintained open source project.

The cloudflare-docs repository on GitHub remains the home for feedback, issues, and pull requests from anyone who wants to improve the documentation.