2025 1206 Hugo non-page HTML resource

I use Hugo on this site, which automatically processes HTML and Markdown files in page bundles. So for instance, content/blog/first-post/index.html isn’t copied verbatim to the site output, but it is templated with my theme and so forth. Hugo does this automatically with all HTML and Markdown files.

But sometimes I need to copy an HTML or Markdown file verbatim to the output — for instance, if the HTML file was prepared outside of Hugo to be standalone, where Hugo’s templating might interfere with proper display. One example is this slide show from a talk I gave (over ten years ago now!). It uses HTML Slidy, which gets broken by Hugo’s templating.

Hugo doesn’t have a natural way to allow for this, but it is powerful enough to let you build one. tl;dr include this in the template that renders your page¹:

{{- /* Allow a page to provide a list of Resources that would normally be procseed as Pages.
<https://github.com/gohugoio/hugo/issues/12274#issuecomment-2640061092>
*/ -}}
{{- with .Params.ResourcesPassthru -}}
  {{- range . -}}
    {{- $res := $.Resources.Get . -}}
    {{- $publishPath := urls.JoinPath $.RelPermalink $res.Name -}}
    {{- ($res.Content | resources.FromString $publishPath).Publish -}}
  {{- end -}}
{{- end -}}

This allows a page to provide a parameter called ResourcesPassthru containing filenames. For example:

params:
  ResourcesPassthru:
  - livecd.html

Any files listed in that parameter are copied directly to the output without any templating.

Alternative

The easiest thing to do, which doesn’t require any customization at all, is to place the file in static so it gets copied over without any templating. I didn’t like this because it separates the page content from the resources it relies on.

References

• A comment from Hugo developer jmooring about how to accomplish this for all HTML files, which I adapted to take a parameter instead