Migration from valentus-theme :: Demo pages

Do not copy the entire valentus-theme repository. Move only the Theme Demo slice (docs/modules/ROOT/) into this component and leave the guide module in valentus-theme.

Component rename (`theme-demo` → `demo-pages`)

Baseline shared body fixtures use component name demo-pages (docs/demo-pages/). The earlier name theme-demo was too theme-specific; published URLs and playbook start_path values changed in v0.3.0.

Consumers should pin demo-data @ v0.3.0 (or newer), set start_path: docs/demo-pages, and allowlist demo-pages in siteNavTree.

Sidebar nav (v0.3.3+)

Forest root label Demo pages comes from antora.yml title (component name stays demo-pages). Under that root, nav.adoc groups Core (body fixtures + migration) and Extensions (overview, topic pages, optional supplements via extensions-supplements-nav). Pin v0.3.5 or newer for this hierarchy (v0.3.3 forest title Demo pages; avoid v0.3.4); v0.3.1 briefly used the mistaken forest label antora-core. Post-build redirect stubs on deployed demos map /theme-demo/… → /demo-pages/… for bookmarked Pages URLs.

Source inventory (valentus-theme)

Path Notes

Path	Notes
`docs/modules/ROOT/pages/index.adoc`	Demo hub; update xrefs to stay in `demo-pages` component
`typography.adoc`, `code-blocks.adoc`, `admonitions.adoc`, `tables.adoc`, `blocks.adoc`, `lists.adoc`, `images.adoc`	Core AsciiDoc chrome fixtures (~same coverage as `antora-demo` but Valentus-branded copy)
`extensions/` (overview + topic pages; alias `extensions.adoc` on overview)	Tabs, STEM, Kroki/Mermaid samples — coordinate with consumer playbook (Facto vs lean Valentus)
`docs/modules/ROOT/images/diagrams/*`	Themed SVG artifacts (`.mmd`, `.svg`, `.host.svg`, `.theme.json`) — copy with pages; run themed-svg pipeline if paths change
`docs/mermaid-config.json`	Move to `docs/demo-pages/` root or consumer playbook dir
`docs/modules/guide/**`	Keep in `valentus-theme` (product documentation)
`docs/antora.yml` (component `valentus-theme`)	After migration: drop `modules/ROOT/nav.adoc` from nav; guide-only nav

docs/modules/ROOT/pages/index.adoc

Demo hub; update xrefs to stay in demo-pages component

typography.adoc, code-blocks.adoc, admonitions.adoc, tables.adoc, blocks.adoc, lists.adoc, images.adoc

Core AsciiDoc chrome fixtures (~same coverage as antora-demo but Valentus-branded copy)

extensions/ (overview + topic pages; alias extensions.adoc on overview)

Tabs, STEM, Kroki/Mermaid samples — coordinate with consumer playbook (Facto vs lean Valentus)

docs/modules/ROOT/images/diagrams/*

Themed SVG artifacts (.mmd, .svg, .host.svg, .theme.json) — copy with pages; run themed-svg pipeline if paths change

docs/mermaid-config.json

Move to docs/demo-pages/ root or consumer playbook dir

docs/modules/guide/**

Keep in valentus-theme (product documentation)

docs/antora.yml (component valentus-theme)

After migration: drop modules/ROOT/nav.adoc from nav; guide-only nav

CSS / design language (do not duplicate)

Foundational tokens live in the Valentus UI bundle (site-visual.css, --adt-). Extension supplemental CSS should continue to *reference those tokens with fallbacks — not fork palettes into demo-data.

Chassis vs paint: valentus-theme/CHASSIS.md
Fixture-only classes (e.g. .adt-logo-fixture-*) stay in bundle CSS; demo pages keep using them

valentus-theme playbook after migration

antora-playbook.yml — guide + optional xref to external demo-pages source if you want fixtures on Pages without merging repos
antora-playbook-visual-demo.yml — point content.sources at this repo’s docs/demo-pages instead of sibling clone

When pinning a git tag, set branches: [] on that source entry so Antora does not also collect main (duplicate demo-pages nav).

Per-extension fixtures (stay local unless shared)

Location Role

Location	Role
`facto-stack/demo/docs`	Stack-only demos (client Mermaid, lightbox, SoftNav)
`facto-stack/examples/docs`	Kroki bake / themed-svg smoke
`*/examples/docs` in extension repos	Minimal smoke for CI; link here when pages are reused across demos
`antora-demo` (`samples` component)	Generic AsciiDoc syntax reference for the org docs hub

facto-stack/demo/docs

Stack-only demos (client Mermaid, lightbox, SoftNav)

facto-stack/examples/docs

Kroki bake / themed-svg smoke

*/examples/docs in extension repos

Minimal smoke for CI; link here when pages are reused across demos

antora-demo (samples component)

Generic AsciiDoc syntax reference for the org docs hub

Checklist

Confirm component name demo-pages (renamed from theme-demo in v0.3.0)
Copy ROOT pages + images; fix component/version xrefs (index NOTE → external guide link)
Valentus copy approval / cleanup: trim valentus-theme nav to guide-only; document URL change (no HTML redirects on Pages)
Tag demo-data (v0.2.0 baseline migration) and pin consumer playbooks
Rebuild valentus-theme + facto-stack Pages workflows (CI on next push to main)

Completed with valentus-theme @ f28c657 on main.

Published URL mapping (Valentus GitHub Pages)

Before (in-repo ROOT) After (demo-pages from demo-data)

Before (in-repo ROOT)	After (`demo-pages` from demo-data)
`…/valentus-theme/valentus-theme/1.0/` (fixture hub)	`…/valentus-theme/demo-pages//`
`…/valentus-theme/valentus-theme/1.0/typography.html` (and sibling fixture pages)	`…/valentus-theme/demo-pages/~/typography/` (same page names under component `demo-pages`, version `~`)
Guide (unchanged)	`…/valentus-theme/valentus-theme/1.0/guide/…`

…/valentus-theme/valentus-theme/1.0/ (fixture hub)

…/valentus-theme/demo-pages//

…/valentus-theme/valentus-theme/1.0/typography.html (and sibling fixture pages)

…/valentus-theme/demo-pages/~/typography/ (same page names under component demo-pages, version ~)

Guide (unchanged)

…/valentus-theme/valentus-theme/1.0/guide/…

Intermediate URLs under …/theme-demo/~/ (v0.2.x) redirect to …/demo-pages/~/ on sites that run the legacy redirect script.

Facto stack demo canonical fixture tree: facto-stack/demo-pages// (same demo-data source, different site URL).