TechPrufer
Get started
Cloudflare
Cloudflare logoCloudflare · Feature trail

Documentation Generation Tooling

1 post · Nov 2016 – Jan 2025

What this trail covers

Cloudflare's developer documentation platform has evolved from a custom Gatsby-based engine to a Hugo-based static site generator deployed on Cloudflare Pages. This migration significantly improved build performance, developer experience, and content quality by automating Markdown conversion, code formatting, and deployment processes. The new engine leverages a stricter Markdown standard and a more maintainable architecture for managing thousands of documentation pages and contributions. This post details the migration to Astro and Starlight, further enhancing content organization, extensibility, development experience, and CSS management. The migration process utilized ASTs and a utility called astray for efficient content transformation.

All Cloudflare trails
  1. Open source all the way down: Upgrading our developer documentationThis post details the migration of Cloudflare's developer documentation site from Hugo to Astro and Starlight. Key technical contributions include: the use of Astro for enhanced content organization, extensibility, development experience (type-checking, syntax highlighting), JavaScript/TypeScript support, and CSS management (Tailwind, scoped styles). Content collections with Zod schema validation and JSON schema generation for Intellisense are also highlighted. The migration process leveraged Abstract Syntax Trees (ASTs) and the astray utility to transform Markdown content, specifically adapting code block syntax from front matter to opening code fence attributes. The migration involved changing 8,060 files and resulted in a net reduction of 19,624 lines of code.
  2. We rebuilt Cloudflare's developer documentation - here's what we learnedThis post details the migration of Cloudflare's developer documentation from a Gatsby-based engine to Hugo on Cloudflare Pages. Key technical contributions include: developing an automated migration script using AST traversal (mdast-util-from-markdown, mdast-util-to-markdown, astray) to convert MDX to standard Markdown, implementing a Prettier-based code formatter for consistent code snippets and syntax validation, and orchestrating the migration with a Makefile. The migration resulted in over one million changes across nearly 5,000 files, significantly reducing build times and improving developer experience.
  3. Generating Documentation for TypeScript ProjectsThis post introduces the use of TypeScript for generating documentation, contrasting it with JSDoc and highlighting the benefits of type safety and compile-time error checking. It details the adoption of TypeDoc for automated API reference generation, including setup instructions and output structure. The post also explores using TypeDoc's JSON output with Handlebars for custom documentation rendering and demonstrates how to create dynamic links to source code within Markdown files, ensuring documentation stays synchronized with codebase changes.