Section Rendering

Hugo Section Rendering

Authored Markdown pages are split into sections and rendered through a contract pipeline. This lets the generator support legacy layout classes, newer semantic axes, editor metadata, section media, and page-specific styling without turning browser JavaScript into a second renderer.

Pipeline

  1. partials/main.html resolves page-level defaults and calls page/sections/index.html.
  2. page/sections/source-sections.html splits the authored Markdown source into logical sections. For page bundles, it can also stitch bundled child page resources unless stitchSections is disabled.
  3. page/sections/contract.html builds a section contract for each section.
  4. Supporting contract partials resolve attributes, media, profiles, style variables, axis values, and editor metadata.
  5. page/sections/render.html emits the section DOM.

Section Contracts

The contract family under layouts/partials/page/sections/ owns section semantics:

  • section-attr-contract.html: leading section-frame Goldmark attribute block.
  • content-contract.html: trailing content-wrapper attrs such as --- { .wide }.
  • media-detect.html: first/last media extraction and caption detection.
  • profile-contract.html: legacy layout profile and compatibility classes.
  • classify-media-classes.html and class-ownership.html: classify classes authored on media and promote section-owned layout/style/orientation tokens.
  • axis-contract.html: semantic axes such as flow, media_side, size, content_align, surface, and layout_family.
  • style-vars-contract.html: section-scoped CSS variable output.
  • media-contract.html and render-media.html: section media placement.
  • body-contract.html: body source after media/attribute extraction.
  • live-media-wrapper.html: editor-facing wrapper metadata for media blocks.

render.html also handles homepage-banner promotion for the first section when homepage banner config asks for background/hero media behavior.

Repair Guide

Use this ownership split when debugging section output:

  • section splitting or page-bundle stitching: source-sections.html;
  • leading section classes/styles: section-attr-contract.html;
  • trailing content wrapper attrs: content-contract.html;
  • first/last media extraction: media-detect.html;
  • semantic axes and compatibility classes: axis-contract.html, profile-contract.html, and class ownership helpers;
  • final DOM/data attributes: render.html;
  • editor JSON and node identities: page/editor-data.html plus the live node fields emitted by the section contract.

Example authored shape:

{.wrapper .style1 .content-align-left}

Section body text.

![Hero](hero.jpg)

--- { .wide }

The leading attribute block belongs to the section frame. The trailing separator attribute belongs to the content wrapper.

Authoring Boundary

Markdown and front matter remain authoritative. Browser editors may expose section controls, but they should write back to the same Markdown attribute contracts rather than inventing a parallel layout model.

Files To Read

  • layouts/partials/main.html
  • layouts/partials/page/sections/index.html
  • layouts/partials/page/sections/contract.html
  • layouts/partials/page/sections/source-sections.html
  • layouts/partials/page/sections/render.html
  • layouts/partials/page/sections/content-contract.html
  • layouts/partials/page/sections/class-ownership.html
  • layouts/partials/page/editor-data.html