From ae7956cc425e105925b516343adbf97115f7227c Mon Sep 17 00:00:00 2001
From: Lunny Xiao <xiaolunwen@gmail.com>
Date: Sat, 25 Jul 2026 15:14:23 -0700
Subject: [PATCH] Add Cloudflare Pages cache headers for static assets

Cloudflare Pages currently serves all responses with the default
'Cache-Control: public, max-age=0, must-revalidate', including
content-hashed files under /assets/* produced by the Docusaurus
build. Add a static/_headers file so Cloudflare Pages applies
long-lived immutable caching to /assets/* (safe because the filename
changes whenever the content changes) and a conservative one-day
max-age to /img/* and /images/*, which keep stable filenames and can
be replaced in place.

Also exclude _headers from the aws s3 sync step in the publish
workflow, since it is only meaningful for the Cloudflare deployment
and would otherwise be uploaded to S3/CloudFront and become publicly
accessible at /_headers there.
---
 .gitea/workflows/build-and-publish.yaml |  2 +-
 static/_headers                         | 17 +++++++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)
 create mode 100644 static/_headers

diff --git a/.gitea/workflows/build-and-publish.yaml b/.gitea/workflows/build-and-publish.yaml
index 4a115f67..7cbac8b9 100644
--- a/.gitea/workflows/build-and-publish.yaml
+++ b/.gitea/workflows/build-and-publish.yaml
@@ -39,7 +39,7 @@ jobs:
           aws-region: ${{ secrets.AWS_REGION}}
       - name: Copy files to the production website with the AWS CLI
         run: |
-          aws s3 sync build/ s3://docs-gitea-com
+          aws s3 sync build/ s3://docs-gitea-com --exclude "_headers"
           aws cloudfront create-invalidation --distribution-id ${{ secrets.AWS_DISTRIBUTION}} --paths '/*'
       - name: Copy files to Cloudflare Pages
         env:
diff --git a/static/_headers b/static/_headers
new file mode 100644
index 00000000..6e6c1034
--- /dev/null
+++ b/static/_headers
@@ -0,0 +1,17 @@
+# Cloudflare Pages cache headers (only applies to the Cloudflare deployment,
+# see .gitea/workflows/build-and-publish.yaml for the S3/CloudFront exclude)
+
+# Docusaurus content-hashed build output (webpack chunks, css, etc). The
+# filename changes whenever the content changes, so it is safe to cache
+# these for a long time and mark them immutable.
+/assets/*
+  Cache-Control: public, max-age=31536000, immutable
+
+# Files under static/img and static/images keep stable filenames and can be
+# replaced in place (same name, new content), so use a short, conservative
+# max-age instead of immutable caching.
+/img/*
+  Cache-Control: public, max-age=86400
+
+/images/*
+  Cache-Control: public, max-age=86400