Media and Figures

Hugo Media And Figures

Media rendering is a two-layer pipeline: figure wrappers own captions and author-facing figure semantics, while media dispatchers choose how the inner asset should render.

Figure Layer

Figure helpers parse author intent, classes, captions, link behavior, and print metadata before delegating to media rendering. The wrapper owns the <figure> boundary; media partials render the inner image, SVG, iframe, model, video, or fallback content.

Important figure helpers include:

  • layouts/partials/fig/parse.html
  • layouts/partials/fig/wrapper.html
  • layouts/partials/fig/caption.html

Media Dispatch

layouts/partials/media/render.html is the single entry point for inner media content. It classifies local resources, external URLs, HTML/PDF/video embeds, YouTube links, inline SVGs, responsive images, and Three.js model viewers.

layouts/partials/media/utils/find.html resolves the destination. It also owns strict workspace asset matching for authored workspace references, so missing or ambiguous workspace assets fail during the Hugo build instead of silently publishing broken media.

Output Rules

  • Local SVGs render inline through figure/svg.html, never as ordinary <img> output, so embedded TeX/math can be transformed reliably.
  • Responsive raster image processing belongs in the Hugo resource pipeline.
  • HEIC/HEIF destinations resolve to same-basename JPEG/JPG siblings when available; otherwise the source string is rewritten to a JPEG fallback without Hugo resize processing.
  • Local HTML embeds can discover same-basename SVG/PNG/WebP/JPEG fallback images for preview and share surfaces.
  • Local .html, .pdf, video, and model destinations are media types, not ordinary links.
  • Section media uses the section contract before reaching the figure/media renderer.

Files To Read

  • layouts/partials/media/render.html
  • layouts/partials/media/utils/find.html
  • layouts/partials/media/resource-image.html
  • layouts/partials/figure/svg.html
  • layouts/partials/figure/model.html
  • layouts/partials/page/sections/render-media.html