Choosing Local Static Images vs CDN Images
Editorial sites usually pick one default for covers and inline figures: files in the repository static tree, or bytes uploaded to a CDN with a versioned public URL. Both can work with a proposal-digest workflow. They fail in different ways when you mix them carelessly.
Local static images
Local images live under the configured static directory and ship with the site build. Preview, production, and offline review all see the same bytes. Proposal digests can hash local files directly. There is no upload step and no risk of inventing a URL that never existed.
The trade-offs are operational. Large binaries inflate the repo or artifact size. Global cache performance depends on your host (for example Cloudflare Pages) rather than an image-specific CDN. Cross-site reuse means copying files or publishing the whole static tree.
Choose local static images when the corpus is modest, review must work offline, and you want promotion to stay a pure filesystem transaction.
CDN images
CDN images store bytes on an object host and record an https:// URL in front matter. The site build stays small. You can tune caching, formats, and transforms on the CDN. The same asset can appear on more than one property without duplicating git history.
The trade-offs sit in the approval chain. Upload must succeed before the URL is written—never invent a stand-in URL. Digests must bind the exact remote URL to the local bytes you reviewed (via a URL receipt that matches sha256). Preview environments need network access. Broken tokens or renamed objects create production 404s that a local build cannot catch.
Choose CDN images when assets are large, shared, or must be invalidated independently of a full site redeploy—and when you have a reliable upload plus receipt step.
Comparison table
| Concern | Local static | CDN URL |
|---|---|---|
| Preview fidelity | Identical offline | Needs network |
| Proposal binding | File hash in static tree | URL receipt tied to sha256 |
| Repo / artifact size | Grows with binaries | Stays lean |
| Cache control | Host default | CDN rules |
| Failure mode | Missing file in static root | Upload skipped or URL invented |
Hybrid guidance
It is reasonable to keep listing/hero/OG crops local for digest simplicity while shipping rare large diagrams to a CDN. Document which roles are local-only. Do not silently swap a local path for a CDN URL after review without a new proposal and owner approval.
Whatever you choose, keep public Markdown references honest: root-relative /img/... paths for local files, absolute https:// URLs for CDN objects, and no /static/ segment in public paths.
For path mechanics see Docusaurus Static Assets and Image Paths. For approval questions see the Publishing FAQ.