Quick answer
- Attachment coverage is usually mixed: some data is mirrored, some is preserved as structured reference.
- You need explicit backup semantics: what is guaranteed binary capture vs what is URL/context capture.
- If you are building from scratch, read the Notion GitHub Backup Guide first, and use the homepage for setup context.
- Full 1:1 restore is not always possible due to Notion API limits, so treat backups as a safety net and audit trail.
What attachment backup should mean in practice
Teams often claim they backed up everything without defining whether that includes downloadable binaries, metadata references, captions, or all of the above. For attachments and images, that ambiguity causes painful surprises during restore work.
A reliable model separates capture into layers: page content snapshot, block-level attachment metadata, and optional binary mirroring where the source permits stable access. If your process does not document those layers, nobody can tell what recovery confidence is.
Why this gets tricky specifically in Notion
Notion block data can contain external URLs, hosted file descriptors, or references that may change behavior over time. A practical backup strategy preserves enough context to reconstruct decisions later, even when direct file replay is imperfect.
If you want this automated with clear coverage boundaries, run scheduled snapshots with deterministic output and failure visibility.
Repository structure that keeps attachment history usable
Attachment backups fail quietly when repository structure is ad-hoc. Keep page snapshots and any file mirrors predictable so commit history can answer real questions: what changed, when, and did binary assets move or disappear.
notion-backup/
workspace/
design-system/
page.md
page.json
assets/
logo-v2.png
icon-set.svg
manifest.jsonEven when you cannot or should not mirror every binary, keeping `page.json` rich enough to represent attachment references lets you preserve the decision trail around those files.
This is the same restore principle across content types: perfect reconstruction is not always guaranteed, but clear historical context is still highly valuable for recovery.
Related guides
Common mistakes
- Assuming every Notion file URL behaves like a permanent, directly restorable blob.
- Capturing attachment references without enough surrounding page context.
- Mixing mirrored binaries and references with no labeling, making restore workflows ambiguous.
- Ignoring repository organization, which creates noisy, untraceable file churn.
- Skipping attachment checks in backup health reviews.
The fix is usually procedural, not magical: define what coverage means, encode it in output, and review coverage drift over time.
If you are doing this DIY
Start with a realistic attachment policy instead of trying to promise perfection on day one. Document exactly which block types are mirrored, which are reference-only, and how your restore team should interpret both.
- Inventory attachment block types in your highest-risk workspace areas.
- Mark each as binary mirror, metadata only, or unsupported.
- Store page snapshots with structured attachment fields in JSON.
- Track failures where attachment fetch/mirror steps fail.
- Run quarterly restore drills using a small representative dataset.
attachment_policy: image_external: metadata_reference image_file: mirror_if_accessible file_upload: mirror_if_accessible video_external: metadata_reference unsupported_types: log_and_alert
That policy-first approach prevents hidden gaps and gives stakeholders a truthful picture of backup confidence.
FAQ
Do Notion backups include images and attachments?
They can include attachment references and metadata, but exact binary coverage depends on source type, permissions, and API/file URL behavior.
Why do some images appear as links in backups instead of downloaded files?
Many Notion blocks expose URLs or file descriptors. Robust backups may preserve references and metadata even when direct long-term binary mirroring is constrained.
Can I rely on Markdown-only output for attachment recovery?
Not safely. Markdown is excellent for readability, but attachment recovery is better with structured JSON context plus clear file handling rules.
What repository structure works best for attachments?
Keep page snapshots and any mirrored binaries in deterministic paths, and document what is reference-only vs mirrored so restore expectations are clear.
Can I do a perfect 1:1 attachment restore?
Not always. Notion API and file URL constraints can limit exact replay. Treat backups as safety net plus audit trail with practical recovery workflows.