Revela

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 when baseUrl is 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:

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

  1. Create a GitHub repository (e.g., my-portfolio)
  2. Upload the contents of your output/ folder
  3. Go to Settings → Pages
  4. Select Branch: main and / (root)
  5. 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 sync before ./revela generate all (see OneDrive Source).

Option 2: Netlify (Drag & Drop)

The easiest option if you're not using Git:

  1. Go to netlify.com and sign up
  2. Drag your output/ folder onto the page
  3. Done! You get a URL like random-name.netlify.app
  4. Optionally connect a custom domain

Option 3: Traditional Web Host (FTP)

If you have existing web hosting (1&1, Strato, HostEurope, etc.):

  1. Open your FTP client (FileZilla, WinSCP, etc.)
  2. Connect to your host
  3. Upload the contents of output/ to your web root (often public_html/ or htdocs/)
  4. 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:

  1. Push your project to GitHub/GitLab

  2. Go to pages.cloudflare.com

  3. Connect your repository

  4. 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 all
    
  5. Output directory: output

Custom Domain

Most hosts support custom domains. General steps:

  1. Buy a domain (Namecheap, Squarespace Domains, etc.)
  2. Add a CNAME record pointing to your host:
    • GitHub Pages: username.github.io
    • Netlify: your-site.netlify.app
  3. Configure the custom domain in your host's settings
  4. 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:

Real Example: revela.website

This documentation site is built with Revela and deployed to GitHub Pages. See: