Runtime Imports

Hugo Runtime Imports

The head/import pipeline loads shared CSS and JavaScript in a controlled order. Site overrides should extend this pipeline rather than hand-rolling core asset tags.

Head Pipeline

layouts/partials/head.html is the head composition entry point. It emits build metadata, CSS, service worker hooks, optional integrations, and the runtime import chain.

layouts/partials/head/css.html owns the stylesheet path, Sass compilation, fingerprinting, and local/development asset behavior.

Runtime Core

layouts/partials/head/import/runtime-core.html is the critical JavaScript chain. It keeps prefetch, jQuery compatibility, Vim/navigation helpers, code copy, cursor presence, custom runtime imports, and editor imports in a stable order.

The actual head path is intentionally mixed:

  1. layout metrics and shared measurement helpers;
  2. Three.js import map;
  3. PhotoSwipe, Mermaid, and KaTeX assets;
  4. runtime-core;
  5. brochure/navigation runtime and SphereList;
  6. configured params.cdnAssets, excluding assets already imported explicitly.

head/import/custom.html still imports many shared widget/runtime assets explicitly because they are part of the generator-owned runtime surface. New shared assets should use the CDN helper path and generator-owned cache busters. Prefer config-driven optional loading when it is truly optional, but do not fork the core chain in site-local head overrides.

Editor Injection

Markdown editor config is emitted through head/import/markdown-editor.html. It should provide source-path and provider metadata to the browser editor while leaving Hugo render hooks as the render authority.

Files To Read

  • layouts/partials/head.html
  • layouts/partials/head/css.html
  • layouts/partials/head/import/runtime-core.html
  • layouts/partials/head/import/custom.html
  • layouts/partials/head/import/markdown-editor.html
  • layouts/partials/helpers/asset-url.html