User Journey
This tour follows one project from an empty folder to a published website, and then through the changes you'll make over the following months.
Setup: The examples use Windows and the Standalone edition (see Installation). Every step works the same on macOS and Linux; only the paths look different.
You can do everything from the interactive menu (run
revelawithout arguments) or with commands. Both are shown. The menu groups commands under Build, Content, Setup, Addons and Info. The CLI Reference lists every command.
1. Create Your Project
Revela treats the folder you start it in as your project. Create an empty folder and start Revela there:
mkdir D:\Photos\MyPortfolio
cd D:\Photos\MyPortfolio
revela
Revela finds no project.json and offers to create a project:
╭─Create Project───────────────────────────────────────────────╮
│ No Project Found │
│ │
│ This directory (MyPortfolio) doesn't contain a Revela │
│ project. Would you like to create one? │
╰──────────────────────────────────────────────────────────────╯
What would you like to do?
> Create New Project
Skip (use menu instead)
Exit
Choose Create New Project. The project wizard asks five things:
- Project settings: a display name (spaces allowed) and, optionally, the URL your site will live at
- Directory paths: where your photos are (
source) and where the site goes (output) - Theme: Lumina
- Image settings: output formats and quality. The defaults are AVIF 75, WebP 85 and JPG 90.
- Site metadata: title, author, description, copyright
After that it offers optional steps, for example connecting a OneDrive folder. Skip them for now.
Tip:
sourcecan point anywhere, for exampleD:\OneDrive\Photos\Portfolio. Revela reads your photos there without copying them. You can change the paths later withrevela config paths.
Your folder now contains:
D:\Photos\MyPortfolio\
├── project.json # Project settings (paths, theme, image formats)
└── site.json # Site metadata (title, author, ...)
2. Add Your Photos
Create a source\ folder and copy your photos into it. Folders become galleries, and the number prefix sets the order:
D:\Photos\MyPortfolio\source\
└── 01 Galleries\
├── 2024 Vacation\
│ ├── beach.jpg
│ └── sunset.jpg
└── 2025 Wedding\
├── cake.jpg
├── church.jpg
└── party.jpg
Top-level folders such as 01 Galleries become navigation sections, and their subfolders become galleries. Numbers are stripped from titles and URLs, so 2024 Vacation ends up at /galleries/2024-vacation/. See Source Structure for filter galleries, text pages and more.
3. Check and Build
Before your first build, let Revela check the project:
revela check
It reports configuration, structure, theme and content problems together with a suggested fix. Errors make revela check exit with code 2; hints (such as "no baseUrl configured") and warnings are just information.
Now build the site: Build → generate → all in the menu, or:
revela generate all
The pipeline runs five steps:
Pipeline: scan → calendar → statistics → pages → images
━━━ Step 1/5: scan ━━━
Scan content and update manifest
╭─Success──────────────────────────────────────────╮
│ Content scan complete! │
│ │
│ Project: My Photography Portfolio │
│ │
│ Statistics: │
│ Galleries: 2 │
│ Images: 5 │
│ Navigation: 4 │
│ Duration: 0.50s │
╰──────────────────────────────────────────────────╯
━━━ Step 2/5: calendar ━━━
Generate availability calendar from iCal data
(no calendar pages yet: skipped)
━━━ Step 3/5: statistics ━━━
Generate statistics JSON from EXIF data
(no statistics pages yet: skipped)
━━━ Step 4/5: pages ━━━
Generate HTML pages from manifest
╭─Success─────────────────────────────────────╮
│ Page rendering complete! │
│ │
│ Statistics: │
│ Pages: 8 │
│ Duration: 0.20s │
╰─────────────────────────────────────────────╯
━━━ Step 5/5: images ━━━
Process images from manifest
Encoding photos ████████████████████ 5/5 (100%) · 2s elapsed
⠋ 8 workers busy · avif 5 · webp 5 · jpg 5
╭─Success──────────────────────────────────────╮
│ Image processing complete! │
│ │
│ Statistics: │
│ Processed: 5 images │
│ Files: 123 created │
│ Size: 2.1 MB (generated) │
│ Duration: 2.57s │
╰──────────────────────────────────────────────╯
✓ Pipeline completed in 3.36s
The output is a complete static website:
D:\Photos\MyPortfolio\
├── .revela\ # Revela's own data (never published)
│ └── core\ # What was scanned, and how the image files in output\ were made
├── output\
│ ├── index.html
│ ├── galleries\
│ │ ├── 2024-vacation\index.html
│ │ └── 2025-wedding\index.html
│ ├── photo\ # One page per photo
│ ├── images\
│ │ └── galleries\2024-vacation\beach\
│ │ ├── 160.avif 160.webp 160.jpg
│ │ ├── 320.avif 320.webp 320.jpg
│ │ └── ... # every theme size, plus the original width
│ └── _assets\ # Theme CSS, JavaScript and fonts
└── source\
Each photo is saved in every size the theme asks for that is smaller than the photo, plus its original width, in each enabled format. See Image Processing.
4. Preview
Choose Build → serve, or run:
revela serve
🌐 Serving D:\Photos\MyPortfolio\output at http://localhost:8080
Press Ctrl+C to stop
Open http://localhost:8080 in your browser. The server does not watch files: after a change, run revela generate all again and refresh the page. See Dev Server.
5. Everyday Changes
Just run revela generate all again after any change. Revela keeps track of what it already did in .revela\ and only redoes what's needed.
Edit, add or remove photos
Edited a photo (re-exported from Lightroom, for example): only that photo is encoded again.
Added a gallery: only the new photos are encoded; the others are reported as cached.
Deleted a photo: it disappears from the pages, but its generated images stay in
output\images\. Remove them with:revela clean images --dry-run # preview revela clean images # delete
Change image quality or formats
Run revela config image (menu: Setup → config → image) and set, for example, AVIF to 70. On the next build, Revela notices the change and re-encodes only the AVIF files. JPG and WebP stay as they are, and you don't need --force.
Enabling a new format creates just that format. Disabling a format stops creating it; revela clean images removes the old files.
Change image sizes
Sizes belong to the theme, in its Configuration/images.json. The Lumina defaults are:
{
"sizes": [160, 320, 480, 640, 720, 960, 1280, 1440, 1920, 2560],
"resizeMode": "longest"
}
To use your own sizes, extract just the size file into your project and edit themes\Lumina\Configuration\images.json:
revela theme extract Lumina --file Configuration/images.json
If you add 3840, the next build creates a 3840 variant for every photo that is wider than 3840 pixels. Nothing else is encoded again. If you remove a size, revela clean images deletes its files. See Themes.
Output folder deleted
If output\ (or part of it) disappears, the next revela generate all recreates whatever is missing.
6. Add an About Page
Create a text page (menu: Content → create → page → text):
revela create page text "02 About" --title "About Me"
This creates source\02 About\_index.revela. Open it in a text editor and write your content in Markdown below the front matter:
+++
title = "About Me"
template = "page"
+++
## Hello!
I'm a landscape and travel photographer based in Berlin.
Rebuild, and the page appears in the navigation. Add hidden = true to keep a page (such as an imprint) out of the navigation. See Creating Pages.
7. Add a Statistics Page
Revela can show which cameras, lenses and settings you use most:
revela create page statistics "03 Statistics" --title "Photo Statistics"
The page uses the statistics/overview template. On the next generate all, the statistics step reads the EXIF data of your photos, and the page shows it as bar charts. See Statistics.
8. Add a Favicon
Put your favicon files in source\_static\favicon\ (everything in _static\ is copied to the output root) and override the theme's Favicon.revela partial. Static Files explains the steps.
9. Publish
Your output\ folder is the finished website. Upload it to any static host: GitHub Pages, Netlify, Cloudflare Pages or your own web space. Set the site's public address first so Revela can generate sitemap.xml:
revela config project --url https://example.com
See Deployment for step-by-step instructions and a ready-made GitHub Actions workflow.
10. Months Later
Come back, drop new photos into source\ and run revela generate all. Revela remembers what it already processed, so only the new photos are encoded.
To start completely fresh, delete everything Revela generated and rebuild:
revela clean all
revela generate all
When Something Goes Wrong
Start with:
revela check
It lists every problem it finds, with the file and a suggested fix, and exits with code 2 if it finds an error. To run a single area, use revela check config, structure, theme, content, slugs or calendar.
Summary: What Triggers Work
| You change… | Revela does… |
|---|---|
| Add a photo | Encodes all variants of the new photo |
| Edit a photo (file size or date changes) | Re-encodes that photo |
| Delete a photo | Removes it from pages; clean images removes its files |
Add a size to images.json |
Creates only the new size |
| Enable a format | Creates only the new format |
| Change a format's quality | Re-encodes only that format |
Change the theme's resizeMode |
Re-encodes all photos |
| Update Revela with a new image pipeline | Re-encodes all photos |
| Delete generated files | Recreates the missing files |
revela generate images --force |
Re-encodes everything |