Why?

Why Obscura Exists

There are great ways to put photography on the web. Hosted platforms like Squarespace or Format are polished and easy to start with. General-purpose static site generators like Hugo or Eleventy are flexible and well-supported. Both are good choices for many photographers.

Obscura exists because neither felt quite right for me. Platforms handle a lot — but I wanted to control how my images are processed and own my files outright. General-purpose generators can do anything — but doing the specific things a photographer needs (responsive image pipelines, EXIF handling, sidecar metadata, gallery structures) meant assembling and configuring pieces that weren't designed for that workflow.

So I built a tool that does exactly one thing: turn a folder of photos and Markdown posts into a portfolio website. Every feature serves that purpose. Every decision is made with a photographer's workflow in mind. It's not better than the alternatives — it's just different, and more opinionated about this one use case. You can see what it includes.

The Philosophy

Opinionated, not configurable. Obscura doesn't have a plugin system. It doesn't support arbitrary content types. It makes strong choices about image processing, metadata handling, and output structure — so you don't have to.

Your files, your terms. Your photos live on your machine. Your metadata is YAML. Your posts are Markdown. Your site is static HTML — no backend, no database, no vendor lock-in. You can host it anywhere and move it anywhere.

Camera-aware by default. Obscura reads EXIF data from your images and surfaces it automatically — camera, lens, settings, date. The sidecar workflow lets you add what the camera doesn't know (titles, locations, captions) without replacing what it does.

Build fast, break loudly. Incremental builds skip unchanged images. A portfolio of 100 photos rebuilds in seconds. When something is actually wrong — a broken shortcode, an unsupported format — Obscura fails immediately and tells you why. Missing EXIF? That's a warning, not a blocker.

The Project

Obscura is open source, built with TypeScript, and developed on GitHub. Contributions, feedback, and feature requests are welcome: Open an issue or start a discussion.

This site — obscura.md — is itself built with Obscura. It serves as both the project homepage and a small demonstration of what the tool produces.