Source: ViewEdit

Build a composable Antora demo

You will end with a multi-component Antora site on GitHub Pages: shared body fixtures from demo-data, your product pages in-repo, Valentus chrome, and (optionally) Facto stack extensions — without copying mock AsciiDoc into every extension repository.

Architecture and rejected alternatives: Demo data catalog. Naming, start_path layout, and versioning rules: demo-data README — pattern authority.

What you are building

The org uses a three-layer model:

  1. Baseline — demo-data component demo-pages (docs/demo-pages/): rich AsciiDoc that exercises Valentus body styles (admonitions, tables, code, images, extension-oriented samples).

  2. Your demo pages — an Antora component under {your-repo}/demo/home (portal + product pages; or examples/docs for extension-only CI smoke).

  3. Compose playbook — YAML that wires git sources, UI bundle, supplemental UI, and @antora-supplemental/facto-stack (or a slimmer extension list).

Generic AsciiDoc syntax tutorials stay in antora-demo (samples); use demo-pages when you need Valentus-branded fixture pages on a stack or Demo pages.

Reference implementation: facto-stack demo/playbook.yml → published stack demo (Overview).

Prerequisites

  • Node.js 20+ and pnpm

  • Git access to clone demo-data (public HTTPS is enough for Antora runtime.fetch)

  • A repository layout with the playbook at the repo root (see Root strategy in Antora deployment)

Step 1 — Start from a playbook skeleton

Copy one of these starting points:

  • Stack demo (recommended) — clone facto-stack and work in demo/ (playbook.yml, supplemental-ui/, demo/home/).

  • Greenfield — antora-github-deploy-template (workflow + minimal playbook), then add the sources from the steps below.

Set site metadata and folder URLs like the stack demo:

site:
  title: My extension demo
  url: https://YOUR_ORG.github.io/YOUR_REPO
  start_page: home::index.adoc

urls:
  html_extension_style: indexify

Hub-style demos name the portal component home / title Home and point site.start_page at home::index.adoc so Pages URLs stay readable (see facto-stack README — hub component naming).

Step 2 — Wire demo-data (demo-pages)

Add a git content source for the baseline catalog. Pin a SemVer tag for reproducible CI; track main only for local preview if you accept drift.

From facto-stack/demo/playbook.yml (paths sanitized for copy-paste):

content:
  sources:
    - url: https://github.com/antora-supplemental/demo-data.git
      tags: [v0.3.5]
      start_path: docs/demo-pages

After publish, fixture pages appear under {site.url}/demo-pages/~/ (same component name, host-agnostic content).

Local dev with a sibling clone: replace the HTTPS URL with a relative path to your demo-data checkout; keep the same start_path.

Step 3 — Add your product component

Create an Antora component for pages only your repo owns — stack behavior proofs, extension smoke, release notes, not the shared typography catalog.

Example layout (facto-stack): one home component holds the portal Overview and all stack demo pages (Mermaid, lightbox, SoftNav). Public entry: …/facto-stack/home/.

demo/
  home/          # component name: home (portal + stack demo pages)
    antora.yml
    modules/ROOT/pages/...
    modules/ROOT/nav.adoc

Register it pointing at your git root:

    - url: ./..
      start_path: demo/home
      branches: HEAD

Use examples/docs when the repo is a single npm extension and CI only needs a tiny nav (separate component name, not home).

Step 4 — Valentus UI and supplemental UI

Point ui.bundle at the rolling Valentus v2 release (same pattern as the stack demo):

ui:
  bundle:
    url: https://github.com/antora-supplemental/valentus-theme/releases/download/v3/ui-bundle.zip
    snapshot: true
  supplemental_files: ./supplemental-ui

Copy supplemental-ui/ patterns from facto-stack/demo/supplemental-ui or Theme products — brand CSS, math/Mermaid assets, and partial overrides live here. Antora does not auto-merge extension UI; Facto members that ship ui/ still need those files copied or loaded via the compose pack.

Step 5 — Register Facto (profile: demo) or a slimmer hub

For a full stack demo (Lunr, page-context, client Mermaid, lightbox, SoftNav, site-nav-tree hooks), register the compose pack:

antora:
  extensions:
    - require: '@antora-supplemental/facto-stack'
      profile: demo
      siteNavTree:
        enabled: true
        include: [home, demo-pages]
        order: [home, demo-pages]

Notes:

  • include uses Antora component names (home, demo-pages from demo-data), not repository names.

  • Adding a content.sources entry does not put that component in the sidebar — you must list it in siteNavTree.include when site-nav-tree is enabled.

  • Theme-only demos can omit Facto and use Valentus alone; see Theme products.

Match AsciiDoc attributes the stack demo sets for Mermaid client mode and page-context (trim to what you need):

asciidoc:
  attributes:
    source-highlighter: highlight.js
    icons: font
    stem: latexmath
    mermaid-client-mode: client
    page-context-active: ''

Install dependencies the same way as facto-stack: pnpm install at the repo root with antora, @antora-supplemental/facto-stack, and peers listed in that repo’s package.json.

Step 6 — Optional site-nav-tree fixture supplement

When you need a multi-root nav forest shared across demos (not just your single component), add a supplement from demo-data:

    # Optional — uncomment when testing site-nav-tree fixtures
    # - url: https://github.com/antora-supplemental/demo-data.git
    #   branches: main
    #   start_path: docs/fixtures/site-nav-tree

Then extend siteNavTree.include with catalog-alpha, catalog-beta, or other component names documented in site-nav-tree fixture README.

Step 7 — Extension-specific demo data (where it lives)

Situation Location

One repo, CI-only smoke

{extension}/examples/docs — minimal nav; compose demo-pages in the playbook instead of duplicating baseline pages

Two or more published demos need the same extra pages

demo-data → docs/fixtures/{scope}/ (one start_path per supplement folder)

Rich Valentus body samples

Always demo-data → docs/demo-pages — never fork the full catalog into your extension repo

Generated listings (narrow exception)

Extension contentCatalog injection — e.g. page-context keyword pages — not general mock docs

Promote fixtures into demo-data only when reuse justifies shared versioning; document the playbook snippet in your extension README under Demo data.

Step 8 — Build locally

From the repo root (where package.json and the playbook live):

pnpm install
pnpm exec antora demo/playbook.yml

Output defaults to build/site (set output.dir in the playbook if you prefer another path).

Preview:

pnpm exec http-server build/site -p 8082

Open http://localhost:8082/ and confirm:

  • Portal / stack pages from your component(s)

  • demo-pages/~/ fixture routes

  • Sidebar forest matches your siteNavTree.include list

Step 9 — Publish to GitHub Pages

Use Actions-based Pages (artifact upload + deploy), not a hand-maintained gh-pages branch. Workflow patterns: Antora on GitHub and Antora deployment.

Typical checklist:

  1. Repo Settings → Pages → Source = GitHub Actions

  2. Workflow checks out the repo, runs pnpm install, runs antora on your playbook path

  3. Upload build/site with actions/upload-pages-artifact, deploy with actions/deploy-pages

  4. Set site.url in the playbook to the final Pages URL (including repo path segment)

The stack demo workflow lives at facto-stack/.github/workflows/deploy.yml.

Step 10 — Author demo pages with page-context

Teaching and hub docs use page-* AsciiDoc attributes so @antora-supplemental/page-context can render audience, author, and usage context. Set page-context-active in the playbook (Facto demo profile does this) so optional fallback blocks stay hidden when the extension runs.

Example header block (match Live docs architecture and real hub pages):

= My demo page
:page-audience: Users evaluating my extension on Valentus
:page-usage-context: Published demo site — not production product docs
:page-orig-author: Your Name
:page-last-author: Your Name
:page-last-edited: 2026-10-16

Reuse attrs on stack-local pages; rely on demo-pages for pre-built samples that already exercise extensions.

Verify success

You should be able to:

  • Build without fetch errors from pinned demo-data tags

  • Navigate across home, your product component, and demo-pages when site-nav-tree is enabled

  • See Lunr search index content from composed sources (Facto hub profile)

  • Open the published URL with demo-pages/~/ fixture paths resolving under your site.url

See also