Reference - Sumaya Fund

Front matter keys

Front matter is the YAML metadata block at the top of each page. Its keys are documented, with examples, in Front matter.

lazysite.conf keys

Site-wide configuration in public_html/lazysite/lazysite.conf. One key-value pair per line.

Value types

Literal string: key: value - used as-is.
Environment variable: key: ${ENV_VAR} - interpolated from the CGI environment. Multiple vars and mixed text supported: ${REQUEST_SCHEME}://${SERVER_NAME}
Remote URL: key: url:https://... - fetched, trimmed, and cached with the page.
Directory scan: key: scan:/path/*.md sort=field dir - returns array of page objects.

Recognised keys

site_name: Site name. Used in the layout template title and header.
site_url: Site URL. Typically ${REQUEST_SCHEME}://${SERVER_NAME} so the same config works on staging and production.
layout: Active layout name. The processor resolves it to lazysite/layouts/NAME/layout.tt. May also be a remote URL.
theme: Active theme name. The processor resolves it to lazysite/layouts/LAYOUT/themes/THEME/theme.json. The theme's layouts[] array must contain the active layout or the theme is skipped with a warning.
layouts_repo: GitHub OWNER/REPO path for the manager's "Install from Releases" theme browser. Default unset hides the browser.
nav_file: Navigation file path, docroot-relative. Default: lazysite/nav.conf.
search_default: Site-wide default for the search: front matter key. Set to true (default) or false. Pages without an explicit search: key inherit this value.
manager: enabled or disabled. Controls the built-in manager UI at /manager.
manager_path: URL path for the manager. Default: /manager.
manager_groups (retired - SM138): Retired. Manager access is the ui capability granted to a group (Groups page); on upgrade any group this key named receives its capabilities and the line is removed.
update_channel: The minimum release maturity accepted on upgrade, on the edge < beta < stable ladder: stable takes only certified releases, beta takes beta and stable, any other value (default) accepts every release. Out-of-channel upgrades are skipped and audited. See Update channel.
update_policy: auto or manual (default). Whether the fleet-wide lazysite upgrade --all run on deb-managed hosts upgrades this site; manual sites are skipped. Set with install.pl --policy.
log_level: One of ERROR, WARN, INFO, DEBUG. Default: INFO.
log_format: text (default) or json.
plugins: List of plugin script paths to pre-enable without going through the manager.
auth_default: Site-wide default for the auth: front matter key. Set to required, optional, or none (default).
auth_header_user, auth_header_name, auth_header_email, auth_header_groups: Override the HTTP headers used by an external auth proxy. Defaults: X-Remote-User, X-Remote-Name, X-Remote-Email, X-Remote-Groups.
alias_hosts: Comma-separated list of domain-alias hostnames that serve this site with their own presentation. Requests from other hosts (and the primary) get the base configuration.
alias.<host>.<key>: Per-alias-host override. <key> is limited to site_name, theme, layout, nav_file, search_default; other keys are ignored. Each alias host has its own page-cache slot (lazysite/cache/hosts/), cleared alongside the primary cache. Conf-file only - not settable via the manager or API.

All other keys are available as TT variables in page content and the layout template.

See Configuration for full details.

TT variables

Automatic variables (always available in layout.tt)

page_title: From front matter title:.
page_subtitle: From front matter subtitle:.
page_modified: Human-readable file mtime, e.g. "3 April 2026".
page_modified_iso: ISO 8601 file mtime, e.g. "2026-04-03".
content: Rendered page body HTML. Available in the layout template.
request_uri: Current request path, e.g. /about. Set from REDIRECT_URL or REQUEST_URI.
page_source: Docroot-relative path of the source .md file, e.g. /about.md. Useful for admin bar and edit links.
nav: Navigation array from nav.conf. Each item has label, url, children (array of label/url hashes).
query, params: Query parameter hash. Only populated when query_params: is declared in front matter. params is an alias for query.
year: Current year as a 4-digit string, e.g. 2026.
search_enabled: 1 if a search-results.md (or .url) page exists in the docroot, 0 otherwise.
site_name, site_url: From lazysite.conf.
alias_host: The active domain-alias host (e.g. brand2.example) when the request's Host header matches a declared alias_hosts entry; empty string on the primary host. Useful for per-host branching or canonical links.
layout_name: Active layout name, as sanitised by the processor.
theme: Parsed theme.json (hash) when a compatible theme is active. Access config values as [% theme.config.GROUP.KEY %]. Empty hash when no theme is active.
theme_name: Active theme name. Unset when no compatible theme is active.
theme_assets: URL prefix for active-theme assets. /lazysite-assets/LAYOUT/THEME/ for local themes (nested per D013); /lazysite-assets/CACHE_KEY/ for remote layouts (flat). Unset when no theme is active.
theme_css: Pre-rendered <style>:root { ... } block of CSS custom properties derived from theme.config. Empty string when no theme is active. Naming convention: --theme-GROUP-KEY.

Auth variables

authenticated: 1 if the request carries valid auth headers, 0 otherwise.
auth_user: Username, or empty string if not authenticated.
auth_name: Display name from the proxy header (or built-in auth). May be empty.
auth_email: Email address from the proxy header. May be empty.
auth_groups: Array of group names the user belongs to.
editor: 1 if the authenticated user has manager access (a group grants the ui capability), 0 otherwise. Use in layouts to gate admin UI.

Variable precedence

Site variables (from lazysite.conf) are loaded first. Page variables (from tt_page_var) override site variables of the same name. Automatic variables (page_title, page_subtitle, content, etc.) override both.

Environment variable allowlist

Only these CGI variables may be interpolated via ${VAR} in lazysite.conf:

SERVER_NAME - server hostname
SERVER_PORT - server port
REQUEST_SCHEME - http or https
HTTPS - on if HTTPS
REQUEST_URI - full request URI
REDIRECT_URL - requested page path (e.g. /about)
DOCUMENT_ROOT - filesystem docroot path
SERVER_ADMIN - server admin email

HTTP_HOST is intentionally excluded - it is request-supplied and untrusted. Use SERVER_NAME for host-based URL construction.

Security

Path traversal

sanitise_uri rejects null bytes, .. path segments, and suspicious characters before constructing filesystem paths. After construction, each path is verified with realpath to confirm it resolves within $DOCROOT. Symlinks pointing outside the docroot are rejected.

The same check is applied inside write_html before any file is written, guarding against symlink-based overwrite attacks on the cache output path.

Template Toolkit injection

All values extracted from YAML front matter - including title, subtitle, and tt_page_var entries - have TT directive markers ([% and %]) stripped before entering the template context. register list items are stripped at parse time. This prevents authored content from injecting TT directives into the rendering pipeline.

Fenced div class names

The class name following ::: is validated against /\A[\w][\w-]*\z/ before use. Blocks with class names containing characters outside word characters and hyphens are rejected - the content renders without a wrapper div and a warning is written to the error log.

oEmbed JSON parsing

oEmbed provider responses are parsed with JSON::PP (Perl core module) rather than regex extraction. The html field from the parsed response is injected into the page. Provider responses are trusted as-is - restrict %OEMBED_PROVIDERS in lazysite-processor.pl to known hosts if untrusted providers are a concern in your deployment.

File locations

DOCROOT/
  lazysite/
    lazysite.conf              <- site configuration
    nav.conf                   <- navigation
    layouts/
      NAME/layout.tt           <- layout template
      NAME/layout.json         <- layout metadata (optional)
      NAME/themes/THEME/
        theme.json             <- theme manifest
        main.css               <- theme-scoped CSS
        assets/                <- theme assets (images, fonts)
    manager/
      layout.tt                <- manager UI chrome (internal)
      assets/manager.css       <- manager CSS source
    templates/
      registries/              <- registry templates (.tt)
    auth/
      users                    <- user credentials
      groups                   <- group memberships
    forms/
      FORMNAME.conf            <- per-form target config
      handlers.conf            <- named dispatch handlers
      smtp.conf                <- SMTP connection settings
    cache/
      layouts/                 <- remote-layout cache
      tt/                      <- TT compile cache
    logs/                      <- log files
  lazysite-assets/
    LAYOUT/THEME/              <- web-served theme assets (nested)
  manager/
    assets/
      manager.css              <- manager CSS (mirrored from source)
      cm/                      <- CodeMirror assets
  404.md
  index.md
  [content pages]

Scripts (repo root, copied to site by the installer):
  lazysite-processor.pl        <- main processor
  lazysite-auth.pl             <- built-in auth
  plugins/form-handler.pl     <- form dispatch
  plugins/form-smtp.pl        <- SMTP helper
  lazysite-manager-api.pl      <- manager JSON API
  plugins/payment-demo.pl     <- payment demo helper

Source files:
  *.md                         <- Markdown pages
  *.url                        <- remote page pointers
  *.html                       <- generated cache (auto-created)

Registry output (generated at DOCROOT):
  sitemap.xml                  <- generated from sitemap.xml.tt
  llms.txt                     <- generated from llms.txt.tt
  feed.rss                     <- generated from feed.rss.tt
  feed.atom                    <- generated from feed.atom.tt