User Guide

QuantaLumin Hugo Generator User Guide

The QuantaLumin generator is a shared Hugo theme for building structured websites from Markdown workspaces. It is designed for websites that need repeatable page layouts, reusable content blocks, publication workflows, and optional editing tools without each site maintaining its own theme fork.

Mental Model

A site is made from four layers:

  1. Content: Markdown files, page bundles, front matter, images, and data files owned by the website workspace.
  2. Generator: shared Hugo layouts, shortcodes, render hooks, CSS, and browser runtime provided by this theme.
  3. Site configuration: Hugo config and front matter that select the site archetype, navigation, header behavior, tokens, widgets, locks, and content features.
  4. Published output: generated HTML, CSS, JavaScript, images, indexes, and manifests. This output is not the source of truth.

Authors should normally edit Markdown and configuration. They should not copy or fork shared layouts into an individual website unless the generator itself needs a new shared capability.

What Users Author

Most pages are ordinary Markdown:

---
title: About
summary: A short summary for list pages.
---

# About

Page text goes here.

Pages can add structured sections with fenced blocks and shortcodes. The generator turns these into the shared visual components used across sites.

Common authoring surfaces:

  • page front matter for title, summary, status, layout hints, and locking
  • Markdown body text for prose
  • shortcodes for explicit reusable elements
  • fenced structured blocks for larger sections such as cards, galleries, facts, steps, booking widgets, and worlds
  • data/ files for reusable site-local data

Site Archetypes

A site can declare a broad archetype such as:

brochure
venue
storefront
service-commerce
research
generic

Archetypes guide defaults; they are not separate themes. The same generator still renders every site. Site-specific differences should come from content, configuration, and shared extension points.

Workspaces And Templates

Each website should live in its own workspace. A workspace owns its content, data, images, and local configuration. Template workspaces, such as scientist or group websites, are starting points that can be copied into new workspaces. After copying, the new workspace owns its files.

The generator should remain mounted as a shared theme. Do not create a site-local copy such as:

themes/quantalumin/generator

Use the shared generator path in local and managed builds.

References And Libraries

The refitem shortcode links authored pages to Papis and Calibre references from the workspace-local reference snapshot:

{{</* refitem "papis:books:pfeiffer-the-cell" */>}}
{{</* refitem "calibre:40" "The Cell" */>}}
{{</* refitem "papis:papers:reynolds1950" */>}}

The workspace receives this generated data at:

data/quantalumin/references.json

This lets Hugo builds resolve references locally and deterministically instead of querying the live Papis server during a site build.

Editing And Preview

The browser editor is an editing interface over Markdown files. Hugo remains the rendering authority. If edited content looks different from normal rendered content, the fix should usually be in the Hugo template, shortcode, render hook, or shared runtime, not in a site-local layout fork.

Practical Rules

  • Keep content in the website workspace.
  • Keep shared rendering behavior in the generator.
  • Prefer front matter, params, shortcodes, and structured blocks over local layout overrides.
  • Treat generated public/, resources/_gen/, screenshots, and build output as artifacts.
  • Test shared generator changes against several sites, not only the site that motivated the change.