SHIPPED/TOOLS
Independent developer field guide
Edition 0012026
Stack recipe · Content

Blog or docs site with Astro on Cloudflare Pages

For writers and maintainers who need a low-maintenance Markdown docs site or blog without running a server.

This recipe is assembled from official documentation and was not built end to end for this page.

The parts

Role Tool Why
Framework Astro Astro provides native Markdown and MDX content collections with built-in schema validation and zero client-side JavaScript overhead.
Hosting Cloudflare Pages Cloudflare Pages delivers static web assets directly from Cloudflare global edge network with unlimited bandwidth and Git automation.

Why this stack fits

Documentation and editorial blogs need fast navigation, search engine indexing, and little maintenance. Astro with Cloudflare Pages delivers fast pages and removes the backend server and database to maintain.

Astro is built for publishing structured text. As outlined on the Astro official website and in the Astro getting started guide, Astro compiles templates into static HTML without unnecessary client-side JavaScript. With native support for Astro content collections, authors can validate frontmatter metadata at build time using type-safe schemas, so missing publication dates, broken tags, or invalid author references fail the build before reaching production.

Cloudflare Pages delivers static files through a distributed worldwide edge network. As described on the Cloudflare Pages product page and the Cloudflare Pages documentation, Pages connects directly to Git repositories to build and deploy web applications on every push. Its plans include unlimited bandwidth, so traffic spikes from social platforms or developer forums do not create unexpected bills.

How the components connect

Everything in the editorial workflow lives in version control:

  1. Editorial creation: Authors write documentation guides or blog posts in Markdown (.md) or MDX (.mdx) files located in the src/content/ directory.
  2. Schema validation and compilation: When a commit lands on Git, Astro parses the Markdown files. It checks each entry against the Zod schema defined in src/content.config.ts and renders syntax-highlighted code blocks, headings, and internal links into static HTML pages.
  3. Continuous edge deployment: Cloudflare Pages monitors the Git repository branch. Upon detecting new commits, Pages executes npm run build, captures the static output directory (dist), and distributes the generated HTML, CSS, and static assets across Cloudflare data centers worldwide.
  4. Platform constraints: As noted in the Cloudflare Pages platform limits, individual site asset sizes are capped at 25 MiB, which requires hosting very large downloadable binary assets or large video files on separate object storage.

What it costs to run

Running an Astro documentation or blog site on Cloudflare Pages costs very little:

  • Astro: Fully open source under the MIT license with zero software licensing costs (Astro License).
  • Cloudflare Pages: Operates on a freemium pricing model (Cloudflare Pages documentation). The free plan includes unlimited bandwidth and preview deployments, with build limits, including a monthly builds quota, that fit typical publishing schedules (Cloudflare Pages platform limits).

Because neither component uses a persistent database or charges for API gateways or egress, a documentation or blog site can stay online indefinitely at no ongoing cost.

When to pick something else

Depending on team preferences and editorial structure, alternate choices may be appropriate:

  • Eleventy: If you prefer a lightweight JavaScript static site generator that supports diverse templating languages such as Nunjucks, Eleventy is a good alternative, detailed in the Eleventy documentation.
  • Netlify: If your publishing workflow relies on built-in Netlify Forms, Netlify documentation outlines an alternative Git-based deployment platform with freemium tier options (Netlify Pricing).
  • Vercel: If your organization requires deep Next.js compatibility or preview URLs for every branch, Vercel provides a platform with tiered pricing (Vercel Pricing).

Setup steps

  1. Scaffold a documentation or blog site using npm create astro@latest.
  2. Organize documentation articles and blog posts inside the src/content/ directory using Markdown (.md) or MDX files.
  3. Define a type-safe content collection schema in src/content.config.ts using Astro built-in Zod validation.
  4. Build dynamic route templates in src/pages/[...slug].astro to render Markdown content into responsive HTML layouts.
  5. Push the project repository to GitHub or GitLab.
  6. Connect the repository to Cloudflare Pages via the Cloudflare dashboard, setting the build command to npm run build and the output directory to dist.

Tradeoffs

  • Content editing requires Git commits and pull requests, which may be intimidating for non-technical editorial contributors.
  • Heavy documentation repositories with thousands of Markdown files can lead to longer build times compared to dynamic server-side rendering.
  • Cloudflare Pages enforces platform limits such as a maximum single file asset size of 25 MiB.

Swap options

Framework: Eleventy. Swap to Eleventy for a lightweight JavaScript static site generator that supports several template languages.

Hosting: Netlify, Vercel. Swap to Netlify for built-in Netlify Forms or to Vercel for preview URLs on every branch and deep Next.js support.