Theme Customization

Revela allows you to customize themes without modifying the original theme files. You can:

📦 Extract Theme

Copy the entire theme to your project for full customization.

🎯 Override Files

Extract only specific files (templates, assets, configuration).

🎨 Theme Variables

Modify colors, fonts, and sizes via theme.json.

How It Works

When generating your site, Revela resolves themes with this priority:

Local theme (themes/<name>/) - Highest priority
Installed plugins (NuGet packages)
Default theme (Lumina)

This means: If you have a themes/Lumina/ folder in your project, it takes precedence over the installed Lumina theme.

Extracting a Theme

Full Extraction

Extract an entire theme for complete customization:

# Extract to themes/Lumina/
revela theme extract Lumina

# Extract with custom name
revela theme extract Lumina MyTheme

Interactive Mode

Run without arguments for guided extraction:

revela theme extract

Selective Extraction

Extract only specific files:

# Extract single file
revela theme extract Lumina --file layout.revela

# Extract multiple files
revela theme extract Lumina --file layout.revela --file Assets/styles.css

# Extract entire folder
revela theme extract Lumina --file Assets/

# Configuration only
revela theme extract Lumina --file theme.json

Theme Structure

After extraction, your theme folder looks like this:

your-project/
├── themes/
│   └── Lumina/
│       ├── theme.json             # Theme manifest & variables
│       ├── layout.revela          # Main layout template
│       ├── Assets/                # CSS, JS, fonts, images
│       │   ├── styles.css
│       │   └── scripts.js
│       ├── Body/                  # Body templates
│       │   ├── Gallery.revela
│       │   └── Page.revela
│       └── Partials/              # Partial templates
│           ├── Navigation.revela
│           └── Image.revela
├── source/
├── project.json
└── site.json

Customization Options

Theme Variables (theme.json)

Modify colors, fonts, and other design tokens:

{
  "name": "Lumina",
  "version": "1.0.0",
  "variables": {
    "primary-color": "#2563eb",
    "background-color": "#ffffff",
    "text-color": "#1f2937",
    "font-family": "Inter, sans-serif"
  }
}

Variables are available in templates as {{ theme.primary-color }}.

Templates

Customize HTML output by editing .revela files:

layout.revela - Main page structure:

<!DOCTYPE html>
<html>
<head>
    <title>{{ site.title }} - {{ gallery.title }}</title>
</head>
<body>
    {{ include 'navigation' }}
    {{ body }}
</body>
</html>

Body/Gallery.revela - Gallery page content:

<main class="gallery">
    <h1>{{ gallery.title }}</h1>
    {{ if gallery.body }}
    <div class="description">{{ gallery.body }}</div>
    {{ end }}
    <div class="images">
        {{ for image in images }}
        {{ include 'image' }}
        {{ end }}
    </div>
</main>

Assets (CSS/JS)

Modify styles in Assets/styles.css:

.gallery {
    max-width: 1200px;
    margin: 0 auto;
}

Note: CSS files are static assets — they are copied as-is, not processed through the template engine. Use theme.json variables for customizable design tokens, and reference them in your .revela templates.

Partial Overrides

You don't need to extract the entire theme. Extract only what you want to change:

# Only customize the navigation
revela theme extract Lumina --file Partials/Navigation.revela

# Only change styles
revela theme extract Lumina --file Assets/styles.css

The rest will be loaded from the installed theme.

Workflow Example

1. Start with Default Theme

revela generate all

2. Customize Colors

# Extract only theme.json
revela theme extract Lumina --file theme.json

Edit themes/Lumina/theme.json:

{
  "variables": {
    "primary-color": "#dc2626",
    "background-color": "#0f172a"
  }
}

3. Regenerate

revela generate all

Your customizations are automatically used.

CLI Reference

# Full extraction
revela theme extract Lumina
revela theme extract Lumina MyTheme

# Selective extraction
revela theme extract Lumina --file Body/Gallery.revela
revela theme extract Lumina --file Body/Gallery.revela --file Assets/

# Overwrite existing files
revela theme extract Lumina --force

# Interactive mode
revela theme extract

# List available files
revela theme files
revela theme files --theme Lumina

Tips

Start small - Extract only what you need to change
Version control - Commit your themes/ folder
Use variables - Prefer theme variables over hardcoded values
Test live - Run revela serve to preview changes