jwogrady Work, evidence, and what I make of it
Lab note JRN 26-003done

Two folders for files that are not content, and they behave in opposite ways

Why a screenshot in assets/ never appears at a URL, and what you get in exchange.

Dropped a screenshot into assets/, pointed some markdown at it, got nothing.

What was going on

  • My first thought was that I’d typo’d the path. I hadn’t.
  • It turns out Hugo has two directories for files that aren’t content, and they’re near-opposites.
  • static/ is a photocopier.
    • A file at static/x.png is served at /x.png, byte for byte, no questions asked.
  • assets/ isn’t published at all. It’s raw material.
    • A file in there reaches the output only when a template pulls it through resources.Get, and then at a path Hugo picks.
  • So a plain ![](...) aimed at assets/ resolves to nothing, because nothing is there to resolve to.

The file exists and is simultaneously not on the website.

What you get in exchange

  • Here’s the part I like.
  • Files that go through the pipeline can be resized, converted, minified, fingerprinted.
  • Files in static/ are frozen exactly as you shipped them.
  • That’s not a small difference — it decided how I handle every image on this site, and I didn’t find out how much until later in the afternoon.