Design Decisions

This page documents the architectural decisions that shaped the Antora Themes Gallery.

The Problem

We wanted to create a site that:

  • Indexes Antora themes from the community

  • Shows live previews of each theme

  • Lets theme developers submit their work easily

Approach 1: Centralized Builds (Rejected)

The initial design considered building theme previews on our servers:

How It Would Work

  1. Developer submits repository URL

  2. Our server clones the repo

  3. Runs gulp bundle to build the UI

  4. Runs Antora with sample content

  5. Hosts the result

Why We Rejected It

Issue Details

Security Risk

Running untrusted Handlebars templates and build scripts = potential RCE

Compute Costs

Every theme submission triggers a build job

Maintenance Burden

Need to maintain Docker workers, job queues, etc.

Inconsistency

Different Node versions, build failures, etc.

Approach 2: Decentralized Previews (Adopted)

Instead, we offload builds to the developer’s repository:

How It Works

  1. Developer sets up GitHub Actions in their repo

  2. Action builds theme and deploys to GitHub Pages

  3. Action generates preview.png screenshot

  4. Developer submits repo URL to gallery

  5. Gallery stores metadata and links

Benefits

Benefit Details

Zero Security Risk

We never execute untrusted code

No Compute Costs

Developers use GitHub’s free Actions minutes

Simple Architecture

Gallery is just a metadata database

Developer Control

Full control over their build and demo

Trade-offs

  • Requires developers to set up GitHub Actions

  • Preview consistency depends on developers keeping actions updated

  • Can’t guarantee all previews use the same sample content

We mitigate these with a template repository that developers can fork.

Comparison

Feature Centralized Decentralized

Compute Cost

We pay

Developer pays (free)

Security

High risk

Zero risk

Maintenance

Complex

Simple

Consistency

100%

Variable

References

The original design discussion: