Section Controls

Use reserved section keys to control labels, layout, templates, defaults, and renderer dispatch.

Section Controls

A section is still just a YAML object, but the default section renderer reserves a few keys for behavior.

The main controls are:

label: the visible section label, or false to hide it.
kind: choose a renderer registered by an extension.
template: use a Jinja template for the inside of this section.
background: apply a background image to the section band.
style: pass section-specific style data for templates that use it.
defaults: apply repeated values to child objects.

Everything else is content and is rendered recursively.

YAML

By default, the section label is shown on the left. You can set it to any text you want.

labeled_section:
  label: Clear Label
  content: |
    This section has a custom label.

Clear Label

This section has a custom label.

YAML

Use label: false when the content already carries its own heading or when the section should blend into the page.

quiet_section:
  label: false
  content: |
    ## A Markdown heading inside the content

    The section wrapper remains, but the side label is removed.

A Markdown heading inside the content

The section wrapper remains, but the side label is removed.

YAML

Labels can also be positioned above or below the content.

top_labeled_section:
  label:
    text: A Top Label
    position: top
  content: |
    Top labels are useful for wide sections or visual examples.

A Top Label

Top labels are useful for wide sections or visual examples.

YAML

Use defaults when many child sections should share the same controls. The defaults apply to sibling YAML objects, and explicit child keys still win.

repeated_notes:
  label: Repeated Notes
  defaults:
    label: false

  first:
    content: |
      ### First note
      This child hides its generated side label.

  second:
    content: |
      ### Second note
      This child inherits the same behavior.

Repeated Notes

First note

This child hides its generated side label.

Second note

This child inherits the same behavior.

YAML

Use kind when a section should be rendered by an extension instead of the default section renderer.

This example uses the first-party chapters renderer. A project-specific extension could use the same mechanism for resumes, galleries, courses, experiment reports, dashboards, or anything else.

chapter_example:
  kind: chapters
  label: Chapter Renderer
  content:
    - title: Build
      body: |
        The build starts from `index.yml`.
    - title: Render
      body: |
        Renderers decide how each node becomes HTML.

The build starts from index.yml.

Renderers decide how each node becomes HTML.

Templates

template is the smallest customization escape hatch. At section level it keeps the normal section wrapper, but lets the named Jinja template render the inside of the section.

gallery:
  label: Gallery
  template: assets/templates/gallery.html
  title: First run
  images:
    - assets/run-a.png
    - assets/run-b.png

For reusable behavior, prefer a renderer extension. A renderer can define its own keys, inject CSS or JavaScript into only the pages that need it, copy assets, and participate in the build lifecycle.

Syntax

Default section shape:

section_name:
  label:
    text: Optional custom label
    position: left
  kind: optional-renderer-name
  template: optional/template.html
  background: optional-image.png
  style:
    optional: template data
  defaults:
    label: false

  child_key:
    content: |
      Markdown or nested content

Section controls:

Key	Shape	Meaning
`label`	string	Visible side label.
`label`	`false`	Hide the visible label.
`label`	`{text, position}`	Label text plus `left`, `top`, or `bottom` placement.
`kind`	renderer name	Dispatch this node to another renderer.
`template`	template path	Render the section inside with one Jinja template while keeping the section wrapper.
`background`	image path	Use an image behind the section band.
`style`	dictionary/string	Renderer or template-specific style data.
`defaults`	dictionary	Copy values into child YAML objects unless the child overrides them.
any other key	any value	Child content rendered recursively.

Next

Section controls are enough for small sites. When repeated page shapes start showing up, move that structure into a renderer or extension.