Source: ViewEdit

Demo data catalog for supplemental demos

Demo and preview sites need rich AsciiDoc to exercise Valentus chrome and supplemental extensions. Production org hubs must not depend on this content. This proposal picks a composable layout and rejects alternatives that hide fixtures inside extension code.

Problem

  • facto-stack demo/docs ships only stack-specific pages (client Mermaid, lightbox, SoftNav) — not the full Demo pages set from valentus-theme.

  • antora-demo (samples) covers generic AsciiDoc syntax and is already a content.sources entry on the org docs hub — but it is not Valentus-branded and lacks extension-oriented samples (tabs, themed diagrams, page-context attrs).

  • Extensions increasingly need pages to demo UI (nav filter, search chat, linkinator). Duplicating fixtures per repo does not scale.

Recommendation (summary)

Decision Choice

Primary transport

Git repositories wired as Antora content.sources (multiple start_path values per repo allowed)

Shared base catalog

New demo-data repo — component demo-pages for Valentus body fixtures (migrated from valentus-theme/docs/modules/ROOT)

Generic AsciiDoc

Keep antora-demo; do not merge into demo-data unless we later want one clone URL

Extension-specific smoke

Stay in each extension’s examples/docs or demo/docs until a page is reused by 2+ demos — then optional docs/fixtures/{extension}/ under demo-data

Runtime injection

Do not build a general-purpose extension that injects demo pages via contentCatalog.addFile — exception: narrow generators (e.g. page-context keyword listings)

Styles / tokens

Stay in Valentus ui.bundle (site-visual.css, --valentus-*); extensions reference tokens with CSS fallbacks; demo-data is content-only

Versioning

SemVer tags on demo-data; demo playbooks pin tags or track main explicitly

Design language split (foundational vs extension)

The split you started in valentus-theme remains the source of truth:

  • Chassis / layout contracts — antora-ui-chassis (consumed, not owned); see valentus-theme/CHASSIS.md.

  • Foundational paint + body — bundled in Valentus ui-bundle.zip (site-visual.css, --valentus-canvas, --valentus-elevated, --valentus-ink, --valentus-accent, …).

  • Extension supplemental UI — per-package CSS/JS under ui/ copied into supplemental-ui (Antora does not auto-merge extension UI). Styles should use var(--valentus-*, fallback) so demos work on Valentus and degrade on Default UI.

  • Content fixtures — AsciiDoc pages that use those styles; they belong in demo-data or extension-local examples/docs, not in the theme repo long term.

Fixture-only CSS classes (e.g. .valentus-logo-fixture-grid in guide pages) stay in the theme bundle; demo pages reference them by class name.

Antora wiring patterns

Pattern A — extra content source (preferred)

content:
  sources:
    - url: https://github.com/antora-supplemental/demo-data.git
      branches: main
      start_path: docs/demo-pages
    - url: .
      branches: HEAD
      start_path: demo/docs   # consumer-owned stack pages

Pros: normal Antora aggregation, xrefs, Lunr index, no custom extension. Cons: multi-component nav needs @antora-supplemental/site-nav-tree include allowlist.

Pattern B — extension contentCatalog injection

Used today only for generated artifacts (keyword index pages in page-context). Not recommended for tens of static demo pages — harder to edit, review, and version than git content.

Pattern C — submodule

Avoid for org demos; prefer plain git URLs (same as docs/antora-playbook.yml remotes).

facto-stack demo composition

Target shape:

  1. demo-pages from demo-data — typography, admonitions, tables, extension.adoc-style richness (post-migration).

  2. facto-stack from facto-stack/demo/docs — stack-only behavior proofs.

  3. profile: demo on @antora-supplemental/facto-stack — already enables site-nav-tree + client Mermaid + lightbox.

  4. siteNavTree.include: [home, demo-pages] — curated sidebar forest (facto-stack demo: portal + stack pages under component home).

Org docs hub keeps its own forest (docs, registry, …) and may continue to use antora-demo for samples without pulling demo-pages unless we want redundant syntax pages.

valentus-theme demo site

Today: one component (valentus-theme) with guide + ROOT modules; Pages builds from docs/ in-repo.

After migration:

  • In repo: guide module only (product docs).

  • Optional second source: demo-data demo-pages on antora-playbook.yml if the public Valentus site should still show fixtures without bloating the theme release tarball.

  • Visual overlay worktree: antora-playbook-visual-demo.yml should reference demo-data (not sibling clone hack) once fixtures move.

What valentus demo contains today (migration scope)

  • 8+ ROOT pages: index, typography, code-blocks, admonitions, tables, blocks, lists, images, extensions.

  • Diagram assets: docs/modules/ROOT/images/diagrams/* (mmd, svg, host svg, theme json).

  • Guide module (~15 pages): stays in valentus-theme.

  • Not copied blindly: GitHub README chrome, supplemental-ui, ui-bundle build artifacts, node_modules.

Detail: migration.adoc in demo-data.

Other extensions (survey)

Prescribed pattern authority: demo-data README.

Repo Demo / examples today

site-nav-tree

Supplement in demo-data → docs/fixtures/site-nav-tree (catalog-alpha, catalog-beta); README playbook snippet. Pair with nav-typology on hubs.

nav-typology

No separate fixture component; enable on playbooks that already compose site-nav-tree supplements or hub components. See extension README Demo data.

page-context

Teaching pages use page-* attrs on real docs; stack demos compose demo-pages + Facto. Keyword generator needs live pages in content.sources.

antora-search-chat

Lunr corpus comes from composed sources — add demo-pages (and hub components) rather than duplicating pages in the extension repo.

asciidoc-interactive

Product demo page in-repo (docs/modules/ROOT/pages/demo.adoc); not part of demo-data baseline.

linkinator

Needs outbound links in article prose — compose demo-pages or hub docs; probe wiring stays extension-local (examples/).

extension-lister (Facto)

Generated at publish from registered extensions; demo site needs normal content.sources (facto-stack demo).

soft-nav-page-toc

Multi-page nav + SoftNav: facto-stack demo/docs + demo-pages; not a separate demo-data supplement yet.

mermaid-client / diagram-lightbox

Stack behavior proofs in facto-stack/demo/docs; diagram assets also in demo-pages after migration.

Resolved naming (2026-10)

  • Repo: demo-data (umbrella); split to demo-data-{scope} only when size/license/cadence requires it.

  • Baseline component: demo-pages (docs/demo-pages).

  • Org hub: keep antora-demo samples for generic syntax; add demo-pages only when Valentus-branded fixture pages are wanted on the hub.

Implementation status

  • demo-data — baseline demo-pages migrated from valentus-theme ROOT fixtures (see migration.adoc); site-nav-tree supplement shipped.

  • Valentus cutover (2026-10): valentus-theme is guide-only; Pages composes demo-data @ v0.3.0 (or newer tag). Fixture URLs under component demo-pages (…/demo-pages/~/; legacy theme-demo/ redirects on Pages).

  • facto-stack demo/playbook.yml composes demo-pages @ v0.3.5 + demo/home + optional site-nav-tree supplement nested under Extensions. Forest root Demo pages; sidebar Core + Extensions; extension topics under demo-pages/extensions/ (v0.3.2+ split, v0.3.3+ hierarchy).

  • Agent policy: Dev-Centr skill antora-org-site → demo-data.md; stack demo UX pairs skill demo-site-wiring.

See also