Deployment
After running revela generate all, you have a complete static website in your output/ folder. This guide shows you how to publish it online.
What Gets Generated?
Revela creates a fully self-contained static website:
output/
├── index.html # Your homepage
├── 404.html # "Page not found" page (if the theme provides one, Lumina does)
├── sitemap.xml # Search engine sitemap (if baseUrl configured)
├── galleries/
│ └── vacation/
│ └── index.html # A gallery page
├── photo/ # One page per photo (Lumina's default photo viewer)
├── images/ # Optimized images: images/<gallery>/<photo>/<width>.<format>
└── _assets/ # Theme CSS, JavaScript and fonts
Files from source/_static/ (for example CNAME, robots.txt or favicons) are copied to the output root as well.
The output contains only your site: Revela keeps its own bookkeeping in the project's .revela/ folder, never in output/, so you can upload the whole folder as it is.
No server-side processing needed! Any web host that serves HTML files will work.
Building on a Server or in CI
Encoding images is the slow part of a build (hours for a large library with AVIF). Revela only encodes new or changed photos, as long as it finds both the previous output/ and the project's .revela/ folder, which records how the existing image files were made. On a build server, keep both between runs (for example as a persistent working directory or a CI cache). A fresh checkout without them builds everything from scratch, which is correct, just slower. If a plugin keeps durable data in .revela/ (data it cannot recreate), back that folder up as well.
Sitemap
Revela automatically generates a sitemap.xml for search engine indexing. To enable it,
add baseUrl to your project.json:
{
"project": {
"baseUrl": "https://your-domain.com"
}
}
The sitemap includes all pages with <lastmod> dates. Without baseUrl, the sitemap is
skipped (sitemaps require absolute URLs). You can also set it with revela config project --url https://your-domain.com.
Before you publish: run
revela check. It catches configuration and content problems and reminds you whenbaseUrlis missing.
baseUrl also enables <link rel="canonical"> and absolute Open Graph URLs (og:url,
og:image) on every page, so shared links get a proper preview image.
404 Page
revela generate pages (and generate all) writes a 404.html to the output root, rendered
with your theme's layout and in your site language. It is marked noindex, is not part of the
navigation, and is excluded from sitemap.xml. Because the web server shows it for any missing
URL, all of its links and stylesheets are root-absolute (they start with /, or with your
basePath such as /photos/).
Revela only writes the file; your web server has to serve it for missing pages:
| Host | Setup |
|---|---|
| GitHub Pages, Netlify, Cloudflare Pages | Nothing to do, 404.html is picked up automatically |
revela serve (local preview) |
Nothing to do, missing files get 404.html with status 404 |
| Caddy | handle_errors block, see below |
| nginx | error_page 404 /404.html; |
| Apache | ErrorDocument 404 /404.html (e.g. in .htaccess) |
Caddy:
handle_errors {
@404 expression {err.status_code} == 404
handle @404 {
rewrite * /404.html
file_server
}
}
With a basePath, point the server at that path instead (for example /photos/404.html).
Customize it: change the wording through the notfound.* keys in the theme's
Locales/<language>.json (see Theme Language), or extract and edit
the template with revela theme extract Lumina --file Body/NotFound.revela. A hand-written
source/_static/404.html replaces the generated page entirely. Themes without a
Body/NotFound.revela template produce no 404 page.
Caching
A sensible default for your web server or CDN:
- HTML (
*.htmland directory URLs):Cache-Control: no-cache. Browsers revalidate, so visitors see a new build right away. - Images (
/images/): a long cache, e.g.Cache-Control: public, max-age=2592000(30 days). Variant file names stay the same when you replace a photo under the same name, so only go up to a year withimmutableif you never do that. - Theme assets (
/_assets/): cache for a year,Cache-Control: public, max-age=31536000, immutable. Themes link their CSS and JavaScript throughasset_url, which adds a fingerprint of the file content (main.css?v=3f2a9c1d). Change the file and the URL changes with it, so browsers fetch the new version on the next page view, even home-screen web apps on a phone. Unchanged files keep their URL and stay cached. One exception: files a stylesheet loads by itself (for example a font inurl(fonts/inter.woff2)) have no fingerprint. Give such a file a new name when you change it.
Caddy example:
@html path *.html */
header @html Cache-Control "no-cache"
@images path /images/*
header @images Cache-Control "public, max-age=2592000"
@assets path /_assets/*
header @assets Cache-Control "public, max-age=31536000, immutable"
With a basePath, prefix the paths (for example /photos/_assets/*).
Hosting Options
| Option | Cost | Difficulty | Best For |
|---|---|---|---|
| GitHub Pages | Free | Easy | Developers, version control |
| Netlify | Free tier | Easy | Drag & drop, custom domains |
| Cloudflare Pages | Free tier | Easy | Fast global CDN |
| Traditional Hoster | Varies | Easy | Existing hosting |
| Own Server | Varies | Medium | Full control |
Option 1: GitHub Pages
This is how revela.website is hosted. Free, fast, and integrates with Git.
Manual Upload
- Create a GitHub repository (e.g.,
my-portfolio) - Upload the contents of your
output/folder - Go to Settings → Pages
- Select Branch: main and / (root)
- Your site is live at
https://username.github.io/my-portfolio/
Automated with GitHub Actions
To build and deploy automatically on every push, commit your project (project.json, site.json, source/, and themes/ if you have one) to the repository. Then set Settings → Pages → Source to GitHub Actions and create .github/workflows/deploy.yml:
name: Deploy Portfolio
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Download Revela (Standalone, newest release)
env:
GH_TOKEN: ${{ github.token }}
run: |
TAG=$(gh release list --repo Spectara/Revela --limit 1 --json tagName --jq '.[0].tagName')
gh release download "$TAG" --repo Spectara/Revela --pattern "revela-linux-x64-standalone.tar.gz"
tar -xzf revela-linux-x64-standalone.tar.gz
chmod +x ./revela
- name: Generate site
run: ./revela generate all
- uses: actions/upload-pages-artifact@v5
with:
path: output
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@v5
The Standalone edition has the theme and all plugins built in, so nothing else needs to be installed. To pin a version for reproducible builds, replace $TAG with a release tag such as v0.0.1-beta.21.
Photos in OneDrive? Add
./revela source onedrive syncbefore./revela generate all(see OneDrive Source).
Option 2: Netlify (Drag & Drop)
The easiest option if you're not using Git:
- Go to netlify.com and sign up
- Drag your
output/folder onto the page - Done! You get a URL like
random-name.netlify.app - Optionally connect a custom domain
Option 3: Traditional Web Host (FTP)
If you have existing web hosting (1&1, Strato, HostEurope, etc.):
- Open your FTP client (FileZilla, WinSCP, etc.)
- Connect to your host
- Upload the contents of
output/to your web root (oftenpublic_html/orhtdocs/) - Done!
Using Command Line
# With rsync (Linux/macOS)
rsync -avz --delete output/ user@yourserver:/var/www/html/
# With lftp
lftp -e "mirror -R output/ /public_html; quit" -u user,password ftp.yourhost.com
Option 4: Cloudflare Pages
Fast global CDN with generous free tier:
Push your project to GitHub/GitLab
Go to pages.cloudflare.com
Connect your repository
Build command (downloads the newest Standalone release, then builds):
TAG=$(curl -s https://api.github.com/repos/Spectara/Revela/releases | grep -m1 '"tag_name"' | cut -d '"' -f4) && curl -L "https://github.com/Spectara/Revela/releases/download/$TAG/revela-linux-x64-standalone.tar.gz" | tar xz && ./revela generate allOutput directory:
output
Custom Domain
Most hosts support custom domains. General steps:
- Buy a domain (Namecheap, Squarespace Domains, etc.)
- Add a CNAME record pointing to your host:
- GitHub Pages:
username.github.io - Netlify:
your-site.netlify.app
- GitHub Pages:
- Configure the custom domain in your host's settings
- Wait for DNS propagation (up to 24h)
Tips
Base Path for Subdirectories
If your site is hosted at example.com/photos/ instead of the root:
// project.json
{
"project": {
"basePath": "/photos/"
}
}
Image CDN
For large portfolios, consider hosting images separately on a CDN:
// project.json
{
"project": {
"assetsBasePath": "https://cdn.example.com/images/"
}
}
HTTPS
Always use HTTPS! Most modern hosts provide free SSL certificates:
- GitHub Pages: Automatic
- Netlify: Automatic
- Cloudflare: Automatic
- Traditional: Let's Encrypt (free)
Real Example: revela.website
This documentation site is built with Revela and deployed to GitHub Pages. See:
- Source: samples/revela-website
- Workflow: .github/workflows/deploy-website.yml
- Result: revela.website