Deploy Demos to GitHub Pages

The deploy-demos reusable workflow builds self-contained interactive HTML pages (and optionally animated GIFs) from your guidestar demo configs and deploys them to GitHub Pages. Any repository can call it with a single workflow file — no build scripts or asset management required.

Note

Demos are always deployed to the root of your GitHub Pages site (https://<org>.github.io/<repo>/). Subfolder deployment is not currently supported.

Prerequisites

1. In your repository go to Settings → Pages and set the source to GitHub Actions.

2. Create a guidestar-demos/ directory (or any name you choose) in the repository root with the following layout:

   guidestar-demos/
     my-app.json            # demo config file
     another-demo.json      # one file per demo
     wireframes/
       my-app.html          # wireframe HTML for my-app
       another-demo.html
   

   The wireframe field in each JSON config must match a filename inside the wireframes/ subdirectory. See Demo Options for the full list of config fields.

Calling the Workflow

Create .github/workflows/deploy-demos.yml in your repository:

.github/workflows/deploy-demos.yml (minimal)

name: Deploy Demos

on:
  push:
    branches: [main]
    paths:
      - 'guidestar-demos/**'
  workflow_dispatch:

jobs:
  deploy:
    permissions:
      contents: read
      pages: write
      id-token: write
    uses: spacetelescope/guidestar/.github/workflows/deploy-demos.yml@main
    with:
      demos-dir: guidestar-demos

On every push to main that touches the guidestar-demos/ directory, the workflow will build the interactive HTML pages and publish them to GitHub Pages.

Inputs Reference

Input	Default	Description
demos-dir	guidestar-demos	Directory containing *.json demo config files.
wireframes-dir	(empty)	Directory containing wireframe HTML files. Defaults to <demos-dir>/wireframes when left empty.
record-gifs	false	Also record animated GIF versions of each demo. Adds Playwright + Chromium install time to the run.
fps	10	GIF frame rate (frames per second). Only used when record-gifs: true.
width	800	Viewport width in pixels used when recording GIFs.
index-title	Wireframe Demos	Title shown on the auto-generated index.html landing page.
guidestar-version	(empty)	pip version specifier for sphinx-guidestar, e.g. 0.2.0. Leave empty to use the latest published release.
python-version	3.11	Python version used to run the build.

Demo Config Format

Each JSON file in demos-dir describes one demo. The wireframe field is required; all others are optional.

{
  "wireframe": "my-app.html",
  "title": "My App — Feature Tour",
  "height": "480px",
  "steps": [
    "#sidebar-toggle@1200:click|Open the sidebar",
    "#search-input@1500:type-text=hello world|Type a query",
    "#search-btn@1000:click|Submit the search"
  ],
  "repeat": true,
  "autoStart": true
}

The steps array accepts the same shorthand strings or JSON object format as the Sphinx directive’s :steps: option — see Demo Options for the complete step syntax and all available config fields.

Examples

Interactive HTML only (fastest)

.github/workflows/deploy-demos.yml

name: Deploy Demos
on:
  push:
    branches: [main]
    paths: ['guidestar-demos/**']
  workflow_dispatch:
jobs:
  deploy:
    permissions:
      contents: read
      pages: write
      id-token: write
    uses: spacetelescope/guidestar/.github/workflows/deploy-demos.yml@main
    with:
      demos-dir: guidestar-demos
      index-title: My Project Demos

Once deployed, each demo is accessible at:

https://<org>.github.io/<repo>/my-app.html
https://<org>.github.io/<repo>/another-demo.html
https://<org>.github.io/<repo>/             ← auto-generated index

Interactive HTML + GIF recording

.github/workflows/deploy-demos.yml

name: Deploy Demos
on:
  push:
    branches: [main]
    paths: ['guidestar-demos/**']
  workflow_dispatch:
jobs:
  deploy:
    permissions:
      contents: read
      pages: write
      id-token: write
    uses: spacetelescope/guidestar/.github/workflows/deploy-demos.yml@main
    with:
      demos-dir: guidestar-demos
      record-gifs: true
      fps: 12
      width: 1024

Each demo is built as both an interactive HTML page and an animated GIF:

https://<org>.github.io/<repo>/my-app.html
https://<org>.github.io/<repo>/my-app.gif

Custom wireframes directory

If your wireframes live in a separate directory from the JSON configs:

uses: spacetelescope/guidestar/.github/workflows/deploy-demos.yml@main
with:
  demos-dir: docs/demos
  wireframes-dir: docs/wireframes

Pin to a specific guidestar release

uses: spacetelescope/guidestar/.github/workflows/deploy-demos.yml@main
with:
  demos-dir: guidestar-demos
  guidestar-version: '0.2.0'