Aron PrinsandClaude Opus 5
fe81cdf5a9
## The problem
`https://docs.paperclip.ing/sitemap.xml` contains **zero `<lastmod>`
elements** — 192 pages plus the root, none dated. It has never shipped
one.
The empty line after each `<loc>` is the tell: production *is* running
the current template, it just has nothing to emit.
```xml
<url>
<loc>https://docs.paperclip.ing/guides/welcome/key-concepts/</loc>
</url>
```
## Why
Dates come from per-file git history. The guard added in #113 suppresses
them on a shallow checkout, and it is right to — with one commit, `git
log -1` reports that commit's date for *every* file, so the sitemap
would claim the whole site changed at once and Google would learn to
discount the signal.
Cloudflare Pages builds from a depth-1 clone, and **its clone depth is
not configurable from this repo**. `docs-checks.yml` sets `fetch-depth:
0` for exactly this reason, but that workflow only checks the build —
Pages' Git integration is what deploys. So the guard fired on every
production deploy since #113.
Reproduced locally:
| Build environment | `lastmod` entries |
|---|---|
| Full history | 193, real varied dates |
| `git clone --depth 1` | 0 — output byte-identical to production |
## The change
Try `git fetch --unshallow` (90s timeout) before giving up, and log
which branch it took so the Cloudflare build log answers the question
directly.
## Verification
| Scenario | Result |
|---|---|
| Shallow clone, fetchable remote | 1 commit → 257, **193 dates
emitted** |
| Shallow clone, unreachable remote | logs the git error, omits dates,
**exit 0** |
| Full clone (unchanged path) | unaffected |
| `npm run docs:test` (6 suites) + `npm run sync:test` (38 tests) | pass
|
## What this PR cannot prove
The local test cloned from a `file://` remote, which can always fetch.
**Whether Cloudflare's build container keeps usable credentials for the
remote it cloned from is the entire open question**, and only a real
deploy answers it — hence this PR and its preview.
- Works → preview `sitemap.xml` carries dates, build log says `Full
history fetched`.
- Doesn't → build log says `Could not deepen the shallow checkout:
<reason>`, sitemap is exactly what we ship today. No regression either
way; fall back to deploying from Actions with `fetch-depth: 0`.
## Known, not fixed here
Even with full history, **190 of 193 pages date to `2026-08-25`** —
325c9eb rewrote frontmatter across all 192 pages that day. Truthful, but
nearly signal-free, and it clears `dropUniformLastmod` only because 3
pages differ. It self-heals as pages get edited individually. Widening
that guard to a percentage threshold would suppress dates again today,
so I left it alone.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
Paperclip Docs
Source for the Paperclip documentation site — user guides, API and CLI reference, adapter docs, and deployment notes.
Read the docs: https://docs.paperclip.ing/
What's inside
- Guides — Getting started, core concepts, and day-to-day usage.
- API reference — Control-plane endpoints and payload schemas.
- CLI reference —
paperclipcommand surface. - Adapters — Plugin authoring and the integrations catalogue.
- Deploy — Self-hosting, upgrades, and operational guidance.
The site is a single static shell that renders the Markdown files in docs/ directly — no framework, no build step required to read the raw pages.
Build and deployment
Build a release bundle locally with:
npm run docs:build
Cloudflare Pages is connected directly to paperclipai/paperclip-docs through GitHub. There is no normal Wrangler publish step for this repo:
- Pushes to
maindeploy production athttps://docs.paperclip.ing/. - Pushes to other branches create Cloudflare Pages preview/canary deployments.
- Canary URLs are created by Cloudflare for each deployment, for example
https://92b9a99c.paperclip-docs-74t.pages.dev. Use the URL shown in the Cloudflare Pages deployment row or GitHub deployment/check for the pushed branch and commit.
That auto-deploy is not guaranteed — it has silently failed to fire on a push to main before. After anything reader-facing lands, check the live site rather than the merge, and republish by hand if it's stale:
npm run docs:build
npx wrangler pages deploy .site --project-name paperclip-docs --branch main
Contributing
Spotted a typo, a broken link, or something that could be clearer? There are two easy paths, both linked from the footer of every docs page:
- Suggest an edit — opens the underlying Markdown file in GitHub's web editor. Make the change and submit a PR without leaving the browser.
- Report an issue — opens a prefilled Docs feedback issue with the page URL already attached.
For larger changes, fork the repo and open a PR against main. Screenshots live under docs/user-guides/screenshots/{light,dark}/ and should be provided in both themes when replacing UI captures.
Community
License
Copyright (c) 2026 Paperclip Community.
The Paperclip software is open source — see the main paperclip repository for its license.
The documentation in this repository is licensed under Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0). You may read and share it for non-commercial purposes with attribution. Commercial use of any kind requires prior written permission from the copyright holders. See LICENSE for the full text.