Revela

Configuration

Revela stores project settings in project.json in your project folder. The project wizard creates it when you start revela in a folder that has no project yet (see Installation). revela config project creates it too.

Quick Configuration

Use the interactive config menu:

revela config

Or configure specific settings directly:

revela config theme --set Lumina
revela config paths --source "D:\Photos" --output "dist"
revela config image --formats avif:75,webp:85,jpg:90

revela config site edits site.json. It is interactive and asks for each field the theme defines; keys the theme doesn't define (for example language) are kept.

Scripts and CI: always pass options there. Without a terminal, config project, config serve, config statistics and config onedrive run without options don't prompt: they show which options to pass and exit with 1. config site needs a terminal; in scripts, edit site.json directly. Plugin settings (config onedrive, serve, statistics) are written to project.json, so these commands need a project.

Configuration File Structure

{
  "project": {
    "name": "my-portfolio",
    "baseUrl": "https://example.com",
    "basePath": "/"
  },
  "paths": {
    "source": "source",
    "output": "output"
  },
  "theme": {
    "name": "Lumina"
  },
  "generate": {
    "images": {
      "webp": 85,
      "jpg": 90,
      "avif": 75
    },
    "sorting": {
      "galleries": "asc",
      "images": { "field": "dateTaken", "direction": "desc" }
    }
  }
}

Note: Image sizes are defined by the theme in its Configuration/images.json, not in project.json (see Themes). Every photo gets the theme sizes smaller than the photo, plus its original width. Image format quality (webp, jpg, avif) are flat properties under generate.images. Set one to 0 to disable that format. The optional avifEffort, webpEffort, maxSize and maxDegreeOfParallelism settings trade file size or zoom detail for encoding speed (see Encoding Speed). wideGamut (default true) publishes photos with colors beyond sRGB in Display P3; set it to false for sRGB only (see Wide Gamut).

Language belongs in site.json. A language key in the project section of project.json is rejected with a configuration error. Set "language": "en" in site.json instead (see Site Metadata).

Dependencies and Feeds

Full edition and .NET tool only. The Standalone edition has every official theme and plugin built in and has no commands that install packages, so it doesn't need this section.

Themes and plugins your project needs are listed under dependencies. The global revela.json and your project.json use the same shape; for the same key, project.json wins.

{
  "theme": { "name": "Lumina" },
  "dependencies": {
    "feeds": {
      "test": "../my-feed",                          // folder, relative to this file
      "myFeed": "https://example.com/v3/index.json"   // remote NuGet v3 feed
    },
    "packages": {
      "Spectara.Revela.Themes.Lumina": "1.0.0",
      "Acme.Revela.Watermark": "1.0.0"
    }
  }
}

Feeds from a project need your confirmation. A feed that appears only in project.json (not in your global revela.json) could come from someone else's repository. revela restore, revela plugin install and revela theme install list such feeds and ask before using them. In scripts and CI, pass --allow-project-feeds if you trust them, or add the feed to your global config with revela config feed add.

JSONC: Comments and Trailing Commas

Every Revela configuration file accepts a slightly relaxed JSON dialect, commonly called JSONC. You can use:

{
  "theme": {
    "name": "Lumina"
  },
  "generate": {
    "images": {
      // Quality per format (0 disables that format)
      "webp": 85,
      "jpg": 90,
      "avif": 75,
    },
  },
}

This applies to project.json, site.json, theme.json, images.json, and the global revela.json (see Where Settings Come From).

Heads up: When Revela rewrites one of these files for you, for example with revela plugin install <id> or any revela config command, comments and your original formatting are not preserved. The file is reserialised as pretty-printed JSON. This matches how tools like npm and dotnet user-secrets behave. If you keep important comments in a file, prefer editing it manually.

Editor support

VS Code in the Revela source tree treats every *.json file as JSONC. If you author your own project in another editor and see lint warnings on // comments, associate project.json / site.json with the JSONC language.

Custom Paths

By default, Revela uses a source/ folder for your images and output/ for the generated site. You can customize these paths for advanced workflows.

Configure via CLI

# Interactive
revela config paths

# Direct
revela config paths --source "D:\OneDrive\Photos\Portfolio" --output "dist"

Use Cases

☁️ Cloud Storage Source

Point source to a OneDrive, Dropbox, or iCloud folder. Your photos sync automatically, Revela generates from them.

🌐 Direct Deployment

Output directly to your webserver directory (/var/www/html) without copying files.

📁 Shared Photo Library

Multiple Revela projects can share the same source folder with different filters.

Example: OneDrive Integration

{
  "paths": {
    "source": "D:\\OneDrive\\Photos\\Portfolio",
    "output": "output"
  }
}

Your workflow:

  1. Add photos to OneDrive on any device
  2. They sync to your computer
  3. Run revela generate all to rebuild

Example: Direct Server Deployment

{
  "paths": {
    "source": "source",
    "output": "/var/www/html/photos"
  }
}

After revela generate all, your site is immediately live, with no file copying needed.

Path Resolution

Path Type Example Resolves To
Relative source {project}/source
Relative ../photos {parent}/photos
Absolute D:\Photos D:\Photos
Absolute /var/www/html /var/www/html

Output is disposable. revela clean output deletes the whole output directory (together with Revela's records of what it produced there), and revela clean images deletes unused folders inside it. Both commands refuse to run, and delete nothing, if output is a drive or filesystem root, your home directory, the project folder, the source folder, or a folder that contains any of them. Keep output in a folder that only Revela writes to.

Revela's Own Folder: .revela/

Revela keeps its bookkeeping in a .revela/ folder in your project, never in the output. Revela itself and each plugin have their own folder in it:

Folder What's in it
.revela/core/ What was scanned (photo list, EXIF data) and how the image files in output/ were made
.revela/statistics/ The Statistics plugin's data for each statistics page
.revela/calendar/ The Calendar plugin's data for each calendar page
.revela/compress/ Which .gz/.br files in output/ the Compress plugin created

What a clean command removes depends on what the data is, not on the folder:

Command Removes Next build
revela clean cache Everything Revela can quickly rebuild from your photos: the scan and plugin data Rescans, but encodes no photo again
revela clean output The generated site with everything that describes it: image files, the record of how they were made, compressed files Encodes every photo again
revela clean all Both Starts from scratch

A plugin can also keep durable data that is expensive or impossible to recreate (for example captions written by an AI service). No general clean command ever removes it; only that plugin's own clean command does.

If you use Git, add .revela/ to your .gitignore: it is local build data, like output/. On a build server, keep .revela/ between runs together with output/, and include it in your backups if you use a plugin with durable data.

Available Config Commands

Command Description
revela config Interactive configuration menu
revela config project Project name and URL (--name, --url)
revela config theme Theme and photo viewer (--set, --viewer, --clear-viewer)
revela config site Site metadata in site.json (interactive)
revela config paths Source and output directories (--source, --output)
revela config image Image formats and quality (--formats)
revela config sorting Gallery and image sort order
revela config onedrive / serve / statistics Plugin settings
revela config feed NuGet package sources (Full edition and .NET tool only)
revela config locations Show configuration file paths

Run revela check config to validate your configuration files without building. See the CLI Reference for every option.

Site Metadata

Site-specific content (title, description, copyright, language) is stored separately in site.json:

{
  "title": "My Photography Portfolio",
  "author": "Jane Smith",
  "description": "Landscapes and nature photography",
  "copyright": "© 2026 Jane Smith",
  "language": "en"
}

language defaults to en. It sets the page language, selects the theme's UI text (see Theme Language), and controls month and day names, for example in calendars and format_date.

Configure with:

revela config site

This separation allows you to:

Page-Scoped Assets

Project-specific CSS and JavaScript files live under themes/{theme-name}/Assets/ and are declared in site.json. Use a string for an asset needed everywhere, or an object to limit it to page, template, feature, or plugin scopes:

{
  "stylesheets": [
    "website.css",
    { "path": "prism.css", "scope": ["docs"] }
  ],
  "scripts": [
    { "path": "prism.js", "scope": ["docs"] }
  ]
}

Common scopes are index, gallery, photo, exact template names such as docs, and plugin prefixes such as statistics or calendar. The lightbox feature scope is applied only when the current page resolves to the Lightbox photo viewer.

Assets without a declaration are still copied to _assets, but are not added to generated HTML. See revela.website for the complete customization example.

Where Settings Come From

Revela merges configuration from several sources. Later sources override earlier ones:

  1. Built-in defaults
  2. Global revela.json: next to the Revela executable when that folder is writable (for example an extracted Standalone ZIP), otherwise %APPDATA%/Revela/ on Windows or ~/.config/Revela/ on Linux/macOS. revela config locations shows the path in use.
  3. Project project.json
  4. Project site.json (title, language and the other site fields)
  5. Project logging.json (optional, log levels)
  6. Environment variables prefixed SPECTARA__REVELA__ (use __ to separate nested keys)

Nothing else is read as configuration: no appsettings.json, no environment variables without the prefix, and command-line options only affect the command they belong to.

Environment variables let you override a single setting for one run without editing a file. For example, SPECTARA__REVELA__PLUGINS__SERVE__PORT=3000 changes the dev-server port temporarily, and SPECTARA__REVELA__LOGGING__LOGLEVEL__DEFAULT=Debug turns on detailed logging. They also apply to revela plugin install, revela theme install and revela restore, so CI can supply a feed with SPECTARA__REVELA__DEPENDENCIES__FEEDS__<NAME>=<url-or-absolute-folder>.

Revela reads these files once when a command starts; it does not watch them. Changes made by revela config commands take effect immediately, also in the interactive menu. If you edit a file by hand while the interactive menu is open, restart Revela.

Plugin Settings

Every plugin keeps its settings below plugins, under a short key the plugin defines:

Plugin Key Environment variable prefix
Serve serve SPECTARA__REVELA__PLUGINS__SERVE__
Statistics statistics SPECTARA__REVELA__PLUGINS__STATISTICS__
Source.OneDrive oneDrive SPECTARA__REVELA__PLUGINS__ONEDRIVE__
Source.Calendar calendarFeeds SPECTARA__REVELA__PLUGINS__CALENDARFEEDS__
{
  "plugins": {
    "serve": { "port": 3000 },
    "statistics": { "maxEntriesPerCategory": 20 }
  }
}

If a key below plugins is not used by any installed plugin (for example the typo serv), Revela prints a warning and suggests the closest key.