Deploying an Astro Content Site on Cloudflare Pages

Why Astro + Cloudflare

Astro is a content-first framework that ships zero JavaScript by default. Paired with Cloudflare Pages, you get a globally distributed, fast static site — and with the @astrojs/cloudflare adapter you can keep server-rendered admin routes too.

This tutorial builds devnotes: tutorials and blog posts live as MDX files in Git, and a small admin editor commits new content via the GitHub API, which triggers a fresh Pages build. No database required.

Prerequisites

• Node.js 20+
• A Cloudflare account (free tier is enough)
• A GitHub repository for your content

Step 1 — Scaffold the project

npm create astro@latest -- --template minimal
cd your-project
npm install @astrojs/cloudflare @astrojs/mdx @astrojs/sitemap

Step 2 — Configure the Cloudflare adapter

In astro.config.mjs, set the output to server and add the adapter:

import cloudflare from "@astrojs/cloudflare";
import mdx from "@astrojs/mdx";

export default {
  site: "https://your-domain.pages.dev",
  output: "server",
  adapter: cloudflare(),
  integrations: [mdx()],
};

Step 3 — Author content as MDX

Create src/content/tutorials/my-post.mdx:

---
title: "My First Tutorial"
description: "A short summary for listings and search."
difficulty: "beginner"
tags: ["intro"]
category: "Web"
---

## Section one

Write your body in Markdown.

Step 4 — Deploy

1. Push to GitHub.
2. In Cloudflare Pages, connect the repo and set the build command to npm run build and the output directory to dist.
3. Add your secrets (ADMIN_PASSWORD, GITHUB_TOKEN, …) in the dashboard.

Troubleshooting

• Blank pages after deploy: ensure site in astro.config.mjs is set — canonical URLs and the sitemap depend on it.
• Admin 401s: check GITHUB_TOKEN has Contents: Read/Write on the repo.

Summary

You now have a fast, Git-backed content site on Cloudflare’s edge. Edit in the repo or through the browser admin — every change is a real, reviewable commit.