Site Archetypes

Site Archetypes

The generator now supports an explicit site-level archetype contract. This is the shared way to say what kind of website or workspace a repo is, without forking layouts or pushing theme behavior back into individual site repos.

Config

Preferred config:

[params.site]
archetype = "brochure"

Accepted compatibility keys:

  • params.site.archetype
  • params.qlSite.archetype
  • params.siteArchetype
  • params.site_type
  • params.archetype

Canonical archetypes:

  • brochure
  • blog
  • venue
  • storefront
  • service-commerce
  • research
  • generic

If no archetype is configured, the shared resolver falls back to generic.

Runtime Contract

The shared resolver lives in archetype-contract.html.

The resolved archetype is exposed at runtime through:

  • body classes such as ql-site-archetype-storefront
  • body and main#main-content data attributes:
    • data-ql-site-archetype
    • data-ql-site-family
  • window.QLMarkdownEditor.siteArchetype
  • window.QLMarkdownEditor.siteFamily
  • window.QLMarkdownEditor.siteArchetypeContract

This lets shared CSS, shared templates, and the editor understand the site shape without introducing site-local theme forks.

The backslash insert autocomplete in toggleMarkdown.js also uses the resolved archetype to prioritize recommended structured blocks such as pricing, catalog_grid, and booking for venue sites or facts, gallery, and catalog_grid for storefront sites.

This contract is intentionally broad enough that different products can still share the same authored building blocks. Rawson Hall and TutorLumin are a good example: they are different businesses, but both rely on the same place-network surface built from shared blocks like world, card_grid, steps, calendar, and booking, plus shared shortcodes such as platformfeed and platformportal.

Machine-Readable Catalog

The catalog that drives the resolver lives in site_archetypes.json.

That file is the authority for:

  • archetype labels and descriptions
  • accepted aliases
  • recommended structured blocks
  • recommended widgets
  • expected content patterns

Current Mapping

The intended current mapping is:

  • quantalumin.com: brochure
  • henrysheehy.com: brochure
  • managed Hugo blogs: blog
  • rawsonhall: venue
  • TutorLumin: service-commerce
  • Techno Antiques: storefront
  • Research / PhD: research

Use blog for personal, publication, brand-news, and newsletter-adjacent Hugo sites that are managed through Qloud/Datacentre workspaces. The blog archetype does not change the source-of-truth model: authored posts remain Markdown in a Forgejo-backed workspace, draft editing happens on the workspace draft host, and production/custom domains are deployment targets.

This contract is deliberately small. It should guide editor behavior and shared render defaults, not create a second site-local theming system.