Render Hooks

Hugo Render Hooks

Goldmark render hooks and codeblock renderers are the point where authored Markdown becomes generator-specific HTML or TeX. They are part of the render authority and should not be duplicated in browser editor code.

Main Hook Families

  • render-image.html / render-image.tex: figure/image handling, captions, media dispatch, print metadata, and TeX figure output.
  • render-link.html / render-link.tex: link normalization and output-specific link behavior.
  • render-table.html / render-table.tex: table wrapping, long-table intent, numeric alignment intent, and print/export metadata.
  • render-blockquote.html: callouts, TODO suppression, and styled quotes.
  • render-passthrough.html: math passthrough, equation labels, and KaTeX metadata.
  • render-codeblock.html: fallback codeblock highlighter for languages without a specific hook.

Hugo dispatches language-specific fenced codeblocks directly to render-codeblock-*.html. Structured block hooks such as gallery, booking, coursepurchase, fundalumin, workspace, and world are direct render-hook entry points, not a second dispatch layer inside render-codeblock.html. Many of those hooks have a matching shortcode or TeX renderer. The shortcode docs describe authoring syntax; this page describes the rendering boundary.

Preprocess Layer

layouts/partials/preprocess.html rewrites selected authoring idioms before render hooks see the content. It handles callout-like forms, figure captions, image attributes, math blocks, placement hints, and compatibility transforms. Keep preprocess behavior Hugo-owned; editor code should preserve or hydrate the rendered result, not reimplement the transform.

Implementation Map

  • Shortcode files: layouts/shortcodes/*.html
  • Fenced codeblock hooks: layouts/_default/_markup/render-codeblock-*.html
  • Shared renderers: layouts/partials/etc/*, layouts/partials/widgets/*, and feature-specific partials.
  • Browser hydration: cdn/custom/*.js only after Hugo has emitted the semantic DOM contract.

Files To Read

  • layouts/partials/preprocess.html
  • layouts/_default/_markup/render-image.html
  • layouts/_default/_markup/render-passthrough.html
  • layouts/_default/_markup/render-table.html
  • layouts/_default/_markup/render-blockquote.html
  • layouts/_default/_markup/render-codeblock.html