Revela

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 revela without 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:

  1. Project settings: a display name (spaces allowed) and, optionally, the URL your site will live at
  2. Directory paths: where your photos are (source) and where the site goes (output)
  3. Theme: Lumina
  4. Image settings: output formats and quality. The defaults are AVIF 75, WebP 85 and JPG 90.
  5. Site metadata: title, author, description, copyright

After that it offers optional steps, for example connecting a OneDrive folder. Skip them for now.

Tip: source can point anywhere, for example D:\OneDrive\Photos\Portfolio. Revela reads your photos there without copying them. You can change the paths later with revela 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

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