When a value disappears between Markdown and HTML, trace the boundaries before rewriting the template. This is a debugging method for this site’s Hugo adapter, not a claimed investigation of every path through Hugo’s Go source.

Boundary one: source to page parameters

The author writes root front matter:

node:
  id: example-expression
  name: Example Expression

Hugo exposes root custom fields through page parameters, so the template reads .Params.node.id. The source namespace and the template API are not identical. This compatibility behavior is verified for the site’s pinned version; check it when upgrading rather than assuming it forever.

Boundary two: page to template

Use a minimal reproduction with one content file and a known layout. A layout front matter value can request a specific template. Section, page kind, and output format also influence lookup. Consult the lookup rules for your Hugo version instead of inferring them from a file that happens to work.

This site uses layouts/page.html for regular pages and layouts/list.html for sections, with named layouts for graph and search views.

Boundary three: data to serialization

HTML escaping and JSON serialization solve different problems. Render ordinary text through HTML templates. Build JSON with jsonify. Use a serializer for YAML rather than concatenating strings around nested data.

Round-trip the output when precision matters: parse the rendered data and compare it with the source object. A page can look correct while a newline or scalar type has changed in serialization.

Make failures narrow

  1. Confirm the source parses as expected.
  2. Confirm the intended template is selected.
  3. Inspect the value in that template’s context.
  4. Inspect the generated artifact, not only the browser.
  5. Reduce the example before blaming the wider architecture.

Notebook discipline: record the version, the smallest reproduction, expected behavior, observed behavior, and conclusion. Keep hypotheses labeled until the experiment supports them.