Adding a Structured Block

Adding A Shortcode Or Structured Block

Use this recipe when adding a new authored block to the generator.

Choose The Authoring Shape

  • Use a shortcode when the syntax is naturally inline or shortcode-like.
  • Use a fenced codeblock when authors need YAML/JSON-style structured data.
  • Support both only when there is a real migration or ergonomics reason.

Hugo remains the render authority. Browser code may hydrate or edit the rendered object, but should not become a second renderer.

Implementation Checklist

  1. Add the Hugo render path:
    • shortcode: layouts/shortcodes/<name>.html;
    • fenced block: layouts/_default/_markup/render-codeblock-<name>.html;
    • shared renderer if needed: layouts/partials/etc/*, layouts/partials/widgets/*, or feature-specific partials.
  2. Add TeX output only if the block should work in TeX/PDF output:
    • layouts/shortcodes/<name>.tex;
    • layouts/_default/_markup/render-codeblock-<name>.tex.
  3. Add browser runtime only if the rendered DOM needs hydration:
    • cdn/custom/<name>.js;
    • register through the shared runtime/widget path;
    • handle SPA reinitialization.
  4. Add styles through the shared token/scoped-surface model, not site-local forks.
  5. Update docs:
    • docs/shortcodes.md for authoring syntax;
    • relevant Hugo/JavaScript docs if the block adds a new integration pattern.
  6. Update machine-readable inventories where applicable:
    • docs/shortcodes.manifest.json;
    • docs/structured-blocks.manifest.json;
    • docs/editor-surface.manifest.json;
    • cdn/custom/structured-block-editor-contract.js or its generator scripts when the block is structured-editable.
  7. Test at the narrowest useful level:
    • Hugo build/render check against a fixture page;
    • JS syntax check for new runtime files;
    • browser smoke if the block has SPA/runtime behavior.

Common Boundaries

  • Do not reimplement Hugo render hooks in JavaScript.
  • Do not write HTML as source when Markdown/config can remain source.
  • Keep widget internals scoped to their own token aliases.
  • Keep source docs and manifests synchronized with the new authoring contract.

Files To Read

  • docs/shortcodes.md
  • docs/hugo-render-hooks.md
  • docs/widget-integration-plan.md
  • docs/structured-blocks.manifest.json
  • docs/editor-surface.manifest.json