HUGO

Storing image as asset or page resource?

This is more of a philosophical question, I think. I can not decide on where to store my images. Let’s say I have a page bundle (content/authors/foo/index.html) and that author has a profile picture which is referenced in the front-matter like ‘image: IMG123.jpg’.

AFAIK I can store it in the /assets directory or inside the page bundle (content/authors/foo/IMG123.jpg)

I like the idea of having all the images stored at the same place (/assets/images) but I also like having them encapsulated inside their bundle where they are used.

What is best practice here? Any pros and cons?

assets - location for files that Hugo works with and processes
static - location for files that your website requires and doesn’t change
page bundle - all the files for one single page

So I would store it in static/images and they will be accessible to the website in /images. Or put them in the page bundle and do fancy stuff like responsive images or galleries/slideshows via your templates.

In short: static is quick and uncomplicated, page bundle is template-wise more complicated, but has lots of advantages. Images in assets - nope. Don’t. Only for stuff like watermarking images or processing your favicon or site image.

I do a lot of image resizing so static is not the place for my images. I should have mentioned that.

So you are saying page bundle over assets.

Images in assets - nope. Don’t. Only for stuff like watermarking images or processing your favicon or site image.

I’m curious as to why only stuff like watermarking images and processing favicon is suited for assets and why not also content images? Can you please elaborate?

assets is NOT what you would expect an assets directory of a website to be. It’s Hugo’s asset directory. It was intended to contain everything that is used in Hugo pipes like SCSS, un-processed javascripts and libraries. It’s not your typical “assets” directory in a web project. You can store images there, but then you will have to somehow load them and process them and copy them over to the site. It’s like buying a car with a tape-player just so you can play the tape you want to play. It might work and people might be telling you to use assets as directory for your images, but it is not really the right place.

Gotcha. Intended or not it seems to be working fine having all the images inside assets.

You can store images there, but then you will have to somehow load them and process them and copy them over to the site.

The template code is not much different from having them inside page bundles.

Consider this code where the image is stored inside assets/images and referenced as image: images/IMG123.jpg in the page front-matter.

{{ with .Params.image }}
  {{ with resources.Get . }}
    {{ $img := .Resize "500x" }}
    <img src="{{ $img.RelPermalink }}" />
  {{ end }}
{{ end }}

If that image would belong to the page bundle as a resource I would simply replace resources.Get with .Resources.GetMatch and have the same results.

This is the approach I have used on a couple of websites and no problems so far. But my experience with Hugo is sparse and I this could very well blow up in my face someday.

I am about to setup a new site and I thought I would look into the page bundle method this time and was curious why one would choose one way over the other.

If I have a documentation site with 5 pages, and each page has 2 images, placing all 10 images in the assets directory would be fine.

If I have a documentation site with 1000 pages, and each page has 2 images, I would not want to place all 2000 images in the assets directory. Technically it would be fine, but what if I want to delete 5 pages (and the corresponding images) in the future? Deleting the images would be like searching for 10 needles in a haystack with 2000 straws.

I think of leaf bundles as “content encapsulation.”

More thoughts here

If I have a documentation site with 1000 pages, and each page has 2 images, I would not want to place all 2000 images in the assets directory. Technically it would be fine, but what if I want to delete 5 pages (and the corresponding images) in the future? Deleting the images would be like searching for 10 needles in a haystack with 2000 straws.

That’s very true. Neither of my websites have that many images yet but maybe some day. It is definitely easier to visit a bundle for all related media, as well as deleting it, than having it separated into different folders.

Although I must admit, writing a bash script to search for unused images is something I probably would enjoy. And maybe even useful. But that’s beside the point.

More thoughts here

Thanks! Good ideas in there too.

So if you intend to process images (grayscale, resize etc.) is the best practice to store them in a directory then mount that to assets rather than store them in a sub directory inside assets.

eg.
/assets/uploads = bad practice
/uploads/uploads = good practice

[module]
  [[module.mounts]]
    source = "uploads"
    target = "assets"

Thank you