From 9e8398cc3a7322e3e234187de4db7d69cd34ec46 Mon Sep 17 00:00:00 2001 From: Dotta Date: Tue, 28 Apr 2026 19:23:58 -0500 Subject: [PATCH] Add Cloudflare Pages docs deployment Co-Authored-By: Paperclip --- MAINTENANCE.md | 26 +++++++++++++++++++++++--- package.json | 4 +++- wrangler.jsonc | 6 ++++++ 3 files changed, 32 insertions(+), 4 deletions(-) create mode 100644 wrangler.jsonc diff --git a/MAINTENANCE.md b/MAINTENANCE.md index 48d04d9..0085165 100644 --- a/MAINTENANCE.md +++ b/MAINTENANCE.md @@ -17,7 +17,8 @@ docs/ # Markdown content only ├── deploy/ # Self-hosting & ops docs └── guides/ # Misc long-form guides scripts/ -└── publish-gh-pages.sh # Builds and pushes to the gh-pages branch +└── publish-gh-pages.sh # Builds and pushes to the gh-pages branch fallback +wrangler.jsonc # Cloudflare Pages project config .github/ISSUE_TEMPLATE/ # Support / bug / docs-feedback templates ``` @@ -33,8 +34,11 @@ npm run docs:build:auto # Serve .site/ on http://localhost:4321/ npm run docs:serve -# Build and push to the gh-pages branch +# Build and deploy to Cloudflare Pages npm run docs:publish + +# Build and push to the gh-pages branch fallback +npm run docs:publish:github ``` ## Base paths @@ -95,6 +99,22 @@ If the repo is ever renamed or mirrored, update `DOCS_REPO_SLUG` / `DOCS_REPO_BR ## Publishing +Primary publishing uses Cloudflare Pages, matching the rest of the public Paperclip sites: + +```sh +npm run docs:publish +``` + +That command builds `.site/` and runs: + +```sh +wrangler pages deploy .site --project-name paperclip-docs --branch main +``` + +The Cloudflare Pages project name is `paperclip-docs`; production deploys use branch `main`. + +### GitHub Pages fallback + `scripts/publish-gh-pages.sh` clones the repo into a tempdir, checks out (or creates) `gh-pages`, replaces its contents with a fresh build, commits, and pushes. It leaves the working tree untouched, so it's safe to run with uncommitted changes. A `.nojekyll` marker is added so GitHub Pages serves files whose names start with `_`. -By default, the publish script builds for `https://docs.paperclip.ing/` and writes a `CNAME` file containing `docs.paperclip.ing`. Override with `PAGES_BASE_PATH=/paperclip-docs/ PAGES_CUSTOM_DOMAIN= npm run docs:publish` only when intentionally publishing a GitHub Pages subpath preview without the custom domain. +By default, the publish script builds for `https://docs.paperclip.ing/` and writes a `CNAME` file containing `docs.paperclip.ing`. Override with `PAGES_BASE_PATH=/paperclip-docs/ PAGES_CUSTOM_DOMAIN= npm run docs:publish:github` only when intentionally publishing a GitHub Pages subpath preview without the custom domain. diff --git a/package.json b/package.json index 6601d27..71c835a 100644 --- a/package.json +++ b/package.json @@ -7,6 +7,8 @@ "docs:build:github-subpath": "node site/build-release.mjs --base-path /paperclip-docs/ --out-dir .site", "docs:build:auto": "node site/build-release.mjs --base-path auto --out-dir .site", "docs:serve": "python3 -m http.server 4321 --directory .site", - "docs:publish": "./scripts/publish-gh-pages.sh" + "docs:publish": "npm run docs:publish:cloudflare", + "docs:publish:cloudflare": "npm run docs:build && wrangler pages deploy .site --project-name paperclip-docs --branch main", + "docs:publish:github": "./scripts/publish-gh-pages.sh" } } diff --git a/wrangler.jsonc b/wrangler.jsonc new file mode 100644 index 0000000..ac8990d --- /dev/null +++ b/wrangler.jsonc @@ -0,0 +1,6 @@ +{ + "$schema": "node_modules/wrangler/config-schema.json", + "name": "paperclip-docs", + "compatibility_date": "2026-04-29", + "pages_build_output_dir": ".site" +}