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 statisticsandconfig onedriverun without options don't prompt: they show which options to pass and exit with1.config siteneeds a terminal; in scripts, editsite.jsondirectly. Plugin settings (config onedrive,serve,statistics) are written toproject.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 inproject.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 undergenerate.images. Set one to0to disable that format. The optionalavifEffort,webpEffort,maxSizeandmaxDegreeOfParallelismsettings trade file size or zoom detail for encoding speed (see Encoding Speed).wideGamut(defaulttrue) publishes photos with colors beyond sRGB in Display P3; set it tofalsefor sRGB only (see Wide Gamut).
Language belongs in
site.json. Alanguagekey in theprojectsection ofproject.jsonis rejected with a configuration error. Set"language": "en"insite.jsoninstead (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"
}
}
}
dependencies.packagesmaps a package ID to an exact version.revela plugin install,revela theme installandrevela restorewrite the version that was actually installed. A missing version or"latest"means "newest stable version" (a prerelease build of Revela also picks prereleases).- One file per install. Inside a project,
plugin installandtheme installrecord the package only inproject.json; outside a project only in the globalrevela.json.uninstallremoves the entry from that same file. - Any package ID works. Revela reads whether a package is a theme or a plugin from the package itself, so third-party packages are restored like official ones.
dependencies.feedsmaps a name to a NuGet v3 URL or a folder of.nupkgfiles. Relative folders are resolved from the file that declares them. Remote feeds must usehttps://(plainhttp://only forlocalhost); Revela skips any other feed with a warning, because packages contain code. nuget.org and the bundledpackages/folder are always available.theme.nameis the theme's name from its manifest (for exampleLumina), not a package ID.revela restorelooks it up in your local and installed themes and falls back to the officialSpectara.Revela.Themes.<name>package only when nothing else provides that name.
Feeds from a project need your confirmation. A feed that appears only in
project.json(not in your globalrevela.json) could come from someone else's repository.revela restore,revela plugin installandrevela theme installlist such feeds and ask before using them. In scripts and CI, pass--allow-project-feedsif you trust them, or add the feed to your global config withrevela config feed add.
JSONC: Comments and Trailing Commas
Every Revela configuration file accepts a slightly relaxed JSON dialect, commonly called JSONC. You can use:
- Line comments, like
// this - Block comments, like
/* this */ - Trailing commas at the end of objects and arrays
{
"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 anyrevela configcommand, comments and your original formatting are not preserved. The file is reserialised as pretty-printed JSON. This matches how tools likenpmanddotnet user-secretsbehave. 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:
- Add photos to OneDrive on any device
- They sync to your computer
- Run
revela generate allto 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 outputdeletes the whole output directory (together with Revela's records of what it produced there), andrevela clean imagesdeletes unused folders inside it. Both commands refuse to run, and delete nothing, ifoutputis a drive or filesystem root, your home directory, the project folder, the source folder, or a folder that contains any of them. Keepoutputin 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:
- Share
project.jsonsettings across projects - Keep personal branding in
site.json - Use different site metadata for staging/production
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:
- Built-in defaults
- 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 locationsshows the path in use. - Project
project.json - Project
site.json(title, language and the other site fields) - Project
logging.json(optional, log levels) - 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.