Generator Developer Mental Model

This is the private/developer view of the generator. It is concerned with ownership boundaries, failure modes, and how to change the shared theme without breaking existing sites.

Source Authority

The generator has five authoritative subsystems:

Hugo render authority
  layouts/
  layouts/partials/
  layouts/_default/_markup/
  layouts/shortcodes/

Style authority
  assets/scss/
  assets/css/
  layouts/partials/head/css.html

Frontend runtime authority
  cdn/custom/

Editor authority
  cdn/editor/src/
  cdn/editor/nowtype.min.js
  cdn/custom/toggleMarkdown.js
  scripts/local-markdown-bridge.mjs

PDF and export authority
  browser PDF preview
  browser/Playwright book export
  print/PDF Hugo partials
  legacy TeX compatibility path

Documentation/contracts
  docs/
  docs-site-content/
  data/ql/

Site workspaces own content, configuration, and data. Published output does not own behavior.

Render Pipeline

The render path is:

site Markdown/front matter/data
  -> Hugo content model
  -> preprocess/render hooks/shortcodes
  -> page shell and partial contracts
  -> CSS/token surface
  -> browser runtime hydration
  -> published static site

Important generator contracts:

• layouts/_default/ owns page/list/home shells.
• layouts/partials/page/* owns page chrome, title, section, and editor data contracts.
• layouts/partials/head/* owns the canonical runtime import chain.
• layouts/_default/_markup/ owns Markdown render hooks.
• layouts/partials/preprocess.html owns pre-render textual rewrites.
• assets/scss/main.scss and assets/css/variables.css own the shared style and token surface.

Editor Pipeline

The editor is not a second renderer.

source Markdown
  -> local bridge or workspace provider
  -> Nowtype/edit-mode UI
  -> write Markdown back
  -> Hugo rebuild or SPA refresh

Developer rule: if changing how content renders, change Hugo templates first. Only change editor JavaScript when the editing interface cannot faithfully present or write the source contract.

PDF And Export Pipeline

PDF/export is a separate output pipeline over the same source content. It is not the normal web page with a print button attached.

site Markdown/front matter/data
  -> Hugo render contracts
  -> print/export partials and scoped CSS
  -> browser preview or Playwright export
  -> PDF artifact

Developer rule: keep PDF layout and pagination fixes in the print/export contract first. TeX generation is a compatibility output, not the primary authoring model.

Site And Workspace Boundaries

Sites should not fork shared layouts. The correct escalation path is:

1. Can the behavior be expressed in page front matter or site params?
2. Can an existing shortcode, structured block, or archetype option express it?
3. Can a shared partial accept a new semantic input?
4. Does the generator need a new shared contract?

Only after those fail should a local override be considered, and then it should usually be temporary.

Template Model

Template workspaces are starter content, not alternate themes. A template may contain example pages, images, config, and service entrypoints. The generator continues to supply layout and runtime behavior.

The expected template families are currently:

• scientist/persona websites
• group/lab/organisation websites
• future designer or object-focused website templates

Reference Model

Papis and Calibre data is delivered to workspaces as generated build data:

data/quantalumin/references.json

The generator resolves refitem IDs from that local file. Hugo builds must not query the live Papis or Calibre service.

Change Discipline

Generator changes are fleet-wide. Before committing a behavioral change:

• identify the layer being changed
• avoid touching site-local forks
• update source docs when contracts change
• run the narrowest unit/browser smoke that covers the behavior
• for layout/style/runtime changes, run visual regression captures across the canonical site matrix

Unrelated dirty files are common in this repo. Stage only the files that belong to the current bounded change.