4.1 KiB
Gallery Site Notes
This document owns public-doc-site implementation notes for the v0.4 gallery. Scene example style
rules live in ../scene/examples/STYLE.md.
MkDocs Material Direction
For v0.4, keep the public website and documentation in one MkDocs Material site. The goal is not a separate marketing stack; it is a visual documentation front door backed by reproducible gallery assets. A custom web application becomes useful later only if Datoviz needs live WebGPU embeds, benchmark dashboards, richer release/news pages, or product-level storytelling that MkDocs cannot carry cleanly.
Use this order of complexity:
- Markdown plus Material cards for most index pages.
- Custom CSS in
docs/stylesheets/extra.cssfor Datoviz-specific card grids, image overlays, dark gallery bands, responsive media, badges, and lead cards. - Generated Markdown for gallery pages from example metadata.
- A page-local template override only for the homepage or top gallery index if Markdown becomes too constrained.
- Additional JavaScript only for progressive enhancement such as lightweight filters, media lazy-loading, or WebGPU demo mounting.
Do not fork the Material theme for normal gallery work. Prefer small CSS and template overrides that can survive theme upgrades.
Page Shapes
| Page | Shape |
|---|---|
| Home | compact hero, four-card visual-proof grid, six start links, current status |
| Gallery index | lane overview with large cards for showcases and smaller cards for visual/features |
| Showcase page | one large screenshot or looped video, short thesis, source link, run/capture command, feature tags |
| Visual-family page | controlled baseline image, supported attributes, minimal C example, deferred variants |
| Technique page | before/after or side-by-side image pair, limits, backend requirements |
| Runtime/WebGPU page | explicit experimental labels, supported subset, unsupported-feature diagnostics |
Example cards should use real <img> or <video> elements, not CSS background images, so alt text,
loading behavior, social previews, and future asset checks stay straightforward.
Live WebGPU/WASM Examples
Treat live WebGPU/WASM gallery examples as progressive enhancement over stable PNG or video artifacts. The default gallery artifact remains static media; live execution is an optional browser path for examples where interactivity, animation, or backend proof materially improves the page.
The source of truth remains the normal C example tree plus example metadata. WASM modules, JavaScript bundles, packed assets, generated manifests, and deployment-specific paths are generated artifacts. Do not commit them unless a release-artifact policy explicitly approves the exact files.
Each gallery example may advertise independent capabilities:
| Capability | Meaning |
|---|---|
static-media |
Has PNG and/or video fallback used as the default gallery artifact. |
wasm-supported |
Builds and runs through the portable WASM/WebGPU scene path. |
gallery-live |
Is selected for public live embedding with browser fallback UX. |
Live embeds must:
- load only after user intent or viewport visibility;
- fall back to PNG or video when WebGPU, WASM, assets, or diagnostics fail;
- use the shared scene -> DRP2 -> WebGPU path, not a duplicate gallery renderer;
- be generated by CI/deployment from source examples and metadata;
- report unsupported features honestly.
Data-backed live embeds must use fetched, versioned web bundles instead of growing the base WASM
module with build-time preloaded example data. The bundle contract and migration plan live in
../data/WEBGPU_DATA_BUNDLES.md.
Prefer broad WASM build coverage but curated public embedding. A release can compile many examples
to WASM for validation while showing only a small gallery-live subset on the public gallery.
Front-page card set
Use four visual-proof cards so the homepage reaches onboarding links quickly. Keep the six-card capacity for the separate text-first Start here grid. The current visual set is:
- point cloud;
- brain volume plus transparent mesh;
- wind field;
- choropleth.