Generator System Map

Generator System Map

This file is the shortest path to understanding the generator as a whole.

Source Of Truth

  • Hugo templates and partials under layouts/ are the render authority.
  • Markdown content files in site repos are the authoring authority for page text and structured fenced blocks.
  • Browser editors in cdn/custom/ are editing interfaces, not render-authority.

Main Runtime Layers

Render pipeline

  • Page shells: layouts/_default/
  • Shared partials: layouts/partials/
  • List/summary cards: layouts/partials/views/summary.html
  • Page chrome contract/render shell:
    • layouts/partials/page/chrome-contract.html
    • layouts/partials/page/chrome-render.html
  • Header contract:
    • layouts/partials/page/header-contract.html
  • Render hooks / preprocessors:
    • layouts/_default/_markup/
    • layouts/partials/preprocess.html
  • Newsletter subscription surface:
    • layouts/partials/footer.html
    • layouts/partials/form/newsletter-inner.html
    • layouts/partials/helpers/newsletter-listmonk-config.html

Site/page chrome behavior such as sticky headers is now resolved through the shared header contract. Preferred config lives in params.header.* and page front matter header.*. Older params.chrome.stickyHeader, chrome.stickyHeader, top-level stickyHeader, and the legacy header fixed class are still accepted as compatibility inputs, but they now flow into the same header contract instead of staying separate chrome logic.

List-page summary cards also follow the Hugo render pipeline rather than flattening rendered output. views/summary.html now routes summary sources through a first-paragraph helper, so cards only use the first real paragraph and skip headings, quotes, figures, and similar leading blocks while still preserving inline render output such as passthrough math/KaTeX inside that paragraph. That helper must return a safe HTML fragment rather than escaped tag text because the summary card injects it directly into the rendered card body.

Editorial TODO surfaces also stay draft-only across both supported authoring forms. The fenced todo codeblock and the [!TODO] blockquote/callout path now both suppress output unless site.BuildDrafts is enabled, so author notes do not leak into published pages.

The rendered header shell reads that semantic model in layouts/partials/header.html and passes it down to logo and nav/breadcrumbs, which now prefer params.header.* first and only fall back to legacy HeaderNav.* fields when the semantic fields are not yet present.

Sections are now moving in the same direction. Hugo still emits legacy layout classes for compatibility, but rendered section roots and #editorData now also carry a smaller semantic axis contract:

  • flow
  • media_side
  • size
  • content_align
  • surface
  • layout_family

Those section axes currently appear as data-ql-flow, data-ql-media-side, data-ql-size, data-ql-content-align, data-ql-section-surface, and data-ql-layout-family on each rendered section root.

Shared media/button render hooks also preserve backward compatibility for authored content:

  • local .html media defaults to inline rendering through layouts/partials/figure/html.html, while explicit iframe embeds still use the iframe path
  • the buttons fenced block accepts both standard markdown links and legacy angle-bracket shorthand such as [Label](</path .button .primary>)

The shared newsletter form is also site-configured rather than site-forked. Newsletter copy and list IDs live in params.subscribe.*, while ListMonk transport settings now live in params.subscribe.listmonk.*. That lets different client websites point at different ListMonk nodes without modifying shared partials.

Editor pipeline

  • Edit-mode shell and inspector: cdn/custom/toggleMarkdown.js
  • Nowtype source: cdn/editor/src/
  • Runtime editor bundle: cdn/editor/nowtype.min.js
  • Local file bridge: scripts/local-markdown-bridge.mjs

In replace-main presentation, the editor toolbar belongs to the editor shell flow. Keep it mounted inside the replace-main panel rather than portaling it to document.body; that allows the toolbar to sit above the page surface and push the editing surface down instead of drawing over the page/header chrome.

The replace-main image-preview path also upgrades local SVG figure previews from <img> to inline SVG markup inside cdn/custom/toggleMarkdown.js. Those editor-side inline SVG instances must namespace their internal IDs per preview mount; otherwise duplicated gradients, clip-paths, markers, or <use> targets can collide at document scope and lose paint data in edit mode even though Hugo normal-mode rendering remains correct.

The shared inspector now has a first semantic chrome edit path:

  • when no live section is selected, the Layout tab exposes a Header card
  • that card edits site config params.header.* or page front matter header.*
  • the local bridge exposes:
    • /ops/header/read
    • /ops/header/set
    • /ops/header/unset

The shared inspector also now reads the new section axis contract first for selected live sections. Its current canonical write split is:

  • section-frame semantics write to the section body’s leading { ... } attr block
  • content width and block layout presets write to the section body’s trailing --- { ... } attr block

That keeps Hugo and markdown authoritative while older frontmatter.sections[*] metadata remains a compatibility/editor seam instead of the primary render source.

Style/token pipeline

  • Root + scoped tokens: assets/css/variables.css
  • Shared SCSS entry: assets/scss/main.scss
  • Widget integration contract: docs/widget-integration-plan.md
  • Widget subsystem rule: widget roots alias site tokens into local --widget-* variables, reset shared component leakage locally, and rebuild their own controls explicitly inside that namespace.
  • Shared motion/reveal layer:
    • assets/scss/libs/_animation.scss
    • cdn/custom/fadeAnimation.js
  • Section/layout components:
    • assets/scss/components/_wrapper.scss
    • assets/scss/components/_banner.scss
    • assets/scss/components/_spotlight.scss

Reveal-enabled templates opt in declaratively with data-ql-reveal-* attributes. Current shared knobs are:

  • data-ql-reveal: enable the runtime on a container
  • data-ql-reveal-trigger: reveal mode such as load or enter
  • data-ql-reveal-target: descendant selector to animate
  • data-ql-reveal-order: reveal ordering such as sequence, reverse, or random
  • data-ql-reveal-duration: transition duration
  • data-ql-reveal-base-delay: initial delay before the first target starts
  • data-ql-reveal-stagger: per-item stagger duration

Inline markdown figures still use the shared floated figure-inline contract in assets/scss/components/_figure.scss. The first inline figure after prose still clears prior floats, but back-to-back opposite-side inline figures are allowed to share a row instead of forcing a fresh clear on each figure. That reduces dead whitespace in chapter flows while keeping headings below the float stack.

Authoring Surface

The generator currently supports four main authored input styles:

  1. Normal markdown sections and figures
  2. Structured fenced blocks like team, gallery, contact, faq, stats, testimonials
  3. Hugo shortcodes under layouts/shortcodes/
  4. Front matter / config token overrides

Agent/MCP Documentation Surface

For agents editing sites through an MCP-style protocol, the intended documentation stack is:

The manifest is the canonical inventory for shortcode availability and should be preferred over ad hoc template inference in agents.

Documentation Rule

When adding or changing a shortcode:

  1. update the shortcode implementation in layouts/shortcodes/
  2. update shortcodes.manifest.json
  3. update shortcodes.md if the author-facing contract changed
  4. run scripts/check-shortcode-manifest.mjs

TutorLumin partners with QuantaLumin

You’re connecting to your QuantaLumin account on members.quantalumin.com.