GitHub Action Setup

If you have an existing Antora UI theme, you can add our GitHub Action to enable automatic preview generation.

Prerequisites

Your repository should already have:

  • A valid Antora UI theme structure

  • package.json with build scripts

  • gulpfile.js for bundling

Adding Sample Content

Create a docs/ folder with sample Antora content. This content will be used to generate your preview site.

Minimal Structure

docs/
├── antora.yml
└── modules/
    └── ROOT/
        ├── nav.adoc
        └── pages/
            ├── index.adoc
            └── examples.adoc

antora.yml

name: preview
title: Theme Preview
version: ~
nav:
  - modules/ROOT/nav.adoc

Sample Content Tips

Include examples of all UI elements your theme supports:

  • Headings (all levels)

  • Code blocks (multiple languages)

  • Tables (simple and complex)

  • Admonitions (NOTE, TIP, WARNING, CAUTION, IMPORTANT)

  • Lists (ordered, unordered, nested)

  • Images

  • Links (internal and external)

  • Sidebar navigation (multiple levels)

Adding the Playbook

Create antora-playbook.yml in your repository root:

site:
  title: My Theme Preview
  start_page: preview::index.adoc

content:
  sources:
    - url: .
      start_path: docs

ui:
  bundle:
    url: ./build/ui-bundle.zip
    snapshot: true

output:
  dir: ./build/site

Adding the GitHub Action

Create .github/workflows/preview.yml:

name: Build Preview

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build UI bundle
        run: npx gulp bundle

      - name: Install Antora
        run: npm install @antora/cli @antora/site-generator

      - name: Build preview site
        run: npx antora antora-playbook.yml

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build/site

      - name: Wait for deployment
        run: sleep 30

      - name: Generate preview screenshot
        uses: simonw/shot-scraper-action@v1
        with:
          url: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/
          output: preview.png
          width: 1280
          height: 720

      - name: Commit screenshot
        run: |
          git config user.name "Preview Bot"
          git config user.email "actions@github.com"
          git add preview.png
          git commit -m "Update preview screenshot" || exit 0
          git push

Enable GitHub Pages

  1. Go to your repository Settings

  2. Navigate to Pages

  3. Set Source to GitHub Actions

  4. Save

Trigger the Build

Push your changes to trigger the action:

git add .
git commit -m "Add preview generation"
git push

Verify

After the action completes:

  1. Check that preview.png exists in your repository

  2. Visit https://{username}.github.io/{repo-name}/ to see your preview site

  3. Submit your theme to the gallery

Troubleshooting

Screenshot is blank or wrong

The screenshot is taken 30 seconds after deployment. If your site takes longer to propagate:

- name: Wait for deployment
  run: sleep 60  # Increase wait time

Build fails on gulp bundle

Ensure your package.json has the correct dependencies:

{
  "devDependencies": {
    "gulp": "^4.0.2",
    "gulp-concat": "^2.6.1",
    "gulp-uglify": "^3.0.2"
    // ... other gulp plugins
  }
}

Pages not deploying

Check that:

  • Repository is public

  • GitHub Pages is enabled with "GitHub Actions" source

  • The peaceiris/actions-gh-pages action has correct permissions