Docs: "Why Revela" — honest comparison page (Astro / Hugo / Jekyll)

[kirkone]

Goal

Write an honest, well-structured comparison page for revela.website (and docs/) that proactively answers the recurring question: "Why not just use Astro / Hugo / Jekyll?"

Why

• Saves hours of repeated explanation
• SEO opportunity ("SSG for photographers", "Astro vs Hugo for galleries", etc.)
• Forces clarity on Revela's actual USP
• Demonstrates seriousness — fair comparisons build trust

Blocked by

⛔ #68 — must be done after the Astro spike. Writing this page without hands-on Astro experience would be hand-waving and likely wrong on details.

Proposed structure

Working title: "Why we built Revela (and when you shouldn't use it)"

1. TL;DR — 3-line recommendation per tool
2. The problem we solve — photographers ≠ web developers; folder-as-gallery convention
3. Comparison matrix — Revela / Astro / Hugo / Jekyll across:
   • Folder = gallery convention
   • EXIF auto-extraction
   • Cover image resolution
   • Image pipeline (NetVips / Sharp / native / ImageMagick)
   • Templating language
   • Plugin ecosystem
   • Distribution model
   • Learning curve
   • GUI roadmap
4. When to use what — positive recommendations only ("use Astro if…"), never bashing
5. Honest trade-offs — explicit list of where Revela is currently weaker (no ecosystem, .NET dependency, opinionated)
6. Deep dives — collapsible sections per competitor with code samples from the spike

Hard rules

• ✅ Never bash other tools — frame as "X is great for Y, but if you need Z…"
• ✅ Concrete code examples, not assertions
• ✅ "Last reviewed: , Astro vX, Hugo vY" header — vergleiche altern schnell
• ✅ Author disclaimer: "I built Revela, so I'm biased. Here's my best attempt at fairness."
• ✅ Link to every compared tool's homepage
• ❌ No marketing fluff, no superlatives

Deliverables

• docs/comparison.md (or dedicated route on revela.website)
• Comparison matrix
• "When to use what" section
• Code examples drawn from the spike (Research spike: Rebuild Lumina theme as an Astro integration #68)
• Maintenance commitment: review every 6 months

Risk mitigation

Publish first as docs/why-revela.md (technical audience, low risk). Promote to revela.website only after community feedback.

Priority

Low. Blocked anyway. Pick up when #68 is done and there's appetite for documentation work.

---

Context: discussion with Bertram, May 2026. Companion issue to #68.

[kirkone]

Note: Distribution & runtime requirements deserve top-level placement

Discussion follow-up — this point is strong enough to lead the TL;DR, not be buried in a feature matrix.

Suggested matrix row (prominent placement)

	Revela	Astro	Hugo	Jekyll
Runtime required	None (self-contained) or .NET 10	Node.js 20+	None	Ruby 3+
Single executable	✅	❌ (no working solution)	✅	❌
Offline build	✅	⚠️ (needs npm cache)	✅	⚠️ (needs gem cache)
Update story	Replace binary	npm update + lockfile churn	Replace binary	bundle update
Footprint	~100 MB self-contained / ~10 MB tool	~80 MB Node + 200–500 MB node_modules	~30 MB	~50 MB Ruby + gems

Why this matters for the photographer audience

• Astro cannot be bundled into a single executable. pkg (archived 2024), nexe, Node SEA — all break on Vite/Rollup dynamic imports + native modules (Sharp). This is a Node ecosystem limitation, not an Astro choice.
• Hugo is our direct peer here — single binary, like Revela. Worth acknowledging honestly.
• For non-developer photographers, "download .exe, double-click" vs "install Node, run npm install, hope nothing breaks" is a category difference, not a feature difference.

Suggested TL;DR line

Use Revela if you want a single executable that runs without installing Node or Ruby, and treats every folder of photos as a gallery automatically.

Out-of-scope for #68 (the spike)

The Astro spike does NOT need to attempt a standalone build — it's known impossible. Just confirm the Node dependency in the writeup.