Best Practices: Assets with Content

So now that Hugo CAN have assets bundled with content, I’m curious to know how and why people are using this feature.

Organizing assets for a site is important and I can see the advantages of using the bundled technique when each asset is entirely unique to a piece of page content, but otherwise, I’d think that assets should be organized together so that they can be more easily re-used/referenced.

I’m not challenging the feature or anyone’s use of it, I’m just genuinely curious to know if there are best practices around this, particularly when to use it, when not to. Do people use both methods?


From: Worries about developing news site with thousands of pages and heavy media usage

Well @budparr imagine you have 100k images in one Directory. Nothing is easy to find and reference. In the news business all is speed. Every once in a while you have to search an image for an article.
When the images are all together in one directory - it will drive you crazy.
Even when you use Subdirs under the static folder.
Every image can have a name with sense or just a combination of characters and numbers DCF37773_hhjd–goog.jpg for example.
Its really confusing.
And at the end, we have to realize backups of the whole system. And its best to have everything under content together.
With the new bundle feature it is possible to migrate from our custom WP and the db to hugo. And i am really happy about that.


Thanks for starting this conversation, I’ve wanted to know the same thing about others’ usage.

I am a WordPress, um, person, so I am spoiled on the Media Library and hooking into the upload process, I just use a WordPress site to hold my media, and it outputs the shortcode I copy and paste into my site.

I am looking through my backlog where I want to build a one off web site, which could use the bundles. Maybe an online guide or something.

I do most of my blogging in WordPress still, but I tend to write long form and spend more time in the presentation layer with Hugo, but all my designs lean very minimal, so no bundled assets yet. I really want to see how folks are using it. :slight_smile:


Currently I am my migrating my 14 year old One Drawing Per Day blog (I have this drawing as an avatar for a reason). I’m not into the thousands of posts & images yet -even though I should have been, but I have another life besides blogging).

The new Page Bundles make it much easier for me to use an editor (Sublime Text, Atom etc) as the CMS of my Hugo Project.

In other projects I also have everything organized under /static/ but now I am finding out that having text + images together per year makes for an easier to manage archive and faster local search.

That’s an interesting point. My local text (not code) editor, iA Writer, has a feature where you can essentially include images in a post and I think that would fit nicely into with a iA->Hugo workflow.

Yes. But if you go down this route, make sure to remove the markdown images when rendering the site.

1 Like

Honestly, I wouldn’t recommend any kind of directory structure to a client with thousands of images, whether bundled with content or in a single directory. This is what DAMs are for, and I’m a fan of taking the more UNIX-y approach.

That said, it depends on the underlying business goal of the site and the value of the images to the organization. If the images are stock-ish and only meant as aesthetic supplements to the content, directories are fine. However, if the client has invested a lot of money in creating these assets, directories wouldn’t be my recommendation…

If your 100k images aren’t tagged or categorized, you’ll have a hard time searching your catalog anyway. If you have a good front-end search, searching articles might ease the search for related images because yeah searching text is easier. At this point you might even have to do a query limited to your domain on Google Images :slight_smile:

In the static site generator world, being able to search your media library is something a headless CMS or an external service is responsible for. It’s good that Hugo allow to bundle resources, and being able to add custom Front Matter metadata for Resources will ease the image search even more.

1 Like

I think both ways are valid and great in different situations.

But see this:

  • The concept of grouping files in file directories has survived … Facebook …
  • A filesystem is essentially a NoSQL database (key/value store)
  • For big sites you need some kind of management on top (a CMS, library manager, whatever)
  • Creating an image manager to index a file system is … easy.
  • You could argue that having the images also stored in a database for transactional support would be better, but Hugo’s file system is virtual one, and could be replaced with something smarter.

I have no idea what DAM is, but this is certainly the UNIX-y way to me.

The only real downside to the above is lack of tooling. And when I’m mocking around trying to define a metadata format for the bundles in Hugo, I know well enough that there are no tools out there that supports it. But someone has to start … somewhere.

And for most Hugo sites out there (typical documentation sites with 500 pages, company landing pages etc.), the no-tool but the text editor and GitHub is … very nice in my eyes.

And if you think WordPress got it right, you should read this post:


Digital Asset Management software. Used for example in larger corporations for internal communications such as brand guidelines, campaigns etc. In sort it’s an additional layer of management involving tagging, categorisation etc

DAM on the cheap can be done with the Wordpress media library, there is also Cloudinary etc.

But most DAM solutions (if any) are not free.

I kind of understood what it was a short for, and in general I understand what it does. But how do you integrate it with Hugo? And if you don’t, why do we even talk about it?

I wouldn’t use it myself. Lol!

Don’t have that kind of clients.

If I did you can rest assured that I would become a Hugo sponsor and buy you a holday. :rofl:

DAM is a tool designed to be specifically good at managing digital assets (that is, doing one thing well), hence the UNIX-y comment, but I can see why you’re saying directories are UNIX-y as well. Many newspapers use DAMs or custom CMSs with DAM features (eg, NYT’s Scoop).

I wouldn’t. I’d keep them separate and if the DAM has CDN integration (eg, delivers images directly or maybe pushes to an S3 bucket or whatever), I’d just build shortcodes around whatever the URL conventions are.

Like I said above, I think there are great use cases for generators like Hugo (obviously, it’s my favorite FOSS of all time), and agree with @bep’s metrics for certain, but @budparr is talking about best practices and recommendations. If your client has a lot of valuable image assets, I would be loathe to recommend directories. I also think these decisions are less about tech and more about internal resources and alignment, especially when you have to wear many hats like Bud does (e.g. dev, design, content strategy, editor, etc). You could have everyone using a really strict set of standards and naming conventions, but I’ve never seen that work in the real world with more than 1 or 2 authors (think company shared drives, which IME are a real nightmare).

Sorry I can’t contribute, but I don’t have many well-informed thoughts on WordPress in 2018 :smile:

There are plenty of open source DAMs, and there are costs associated with developer time/energy, so nothing is “free.” A friend is also working on a very large DAM for Northwestern University. ResourceSpace is a big one in the OS world—or at least it was back in 2014-15, when I used to have to research this stuff—if you’re interested @alexandros. I know Rotary uses them, and they obviously have a ton of sites.

Thanks for the suggestions @rdwatters .

If I come across a client who needs something like this I’ll look into DAM solutions more.

Happy New Year by the way! :four_leaf_clover:

1 Like

I’m currently writing a Hugo-powered CMS and being able to use relative paths makes many things much easier.

Main benefits for me:

  • Autocompletion in the editor is easy because
    • All links to related assets in the files are relative
    • Global assets are treated in the same manner but elsewhere
    • Fewer files appear in the list because all stuff that directly belongs to other documents isn’t included
  • Deleting a file and all of its attachments is simple and safe; no chance of deleting shared materials, no need to use any crazy logic or parse any files to see what’s linked
  • Translations can all be part of the same bundle and share assets. This is a big win for bundles in my use case

An example of how a bundle might look

└── trainers
    ├── agatha
    │   ├── data
    │   │   └── agatha.csv
    │   ├── images
    │   │   └── agatha.png
    │   ├──
    │   ├──
    │   └──

I guess from a user’s point of view it might be a bit more friendly if the files were called, etc instead of, but I think that it’s a small price to pay for logically grouping content together and no URL munging is required in the actual CMS.

1 Like

I guess it should be possible for the CMS to abstract that problem away.

1 Like

Yes, under normal use the users won’t ever see the actual filename and everything will just work. This CMS sits on top of a Git repository, and if users clone the content it might take a extra cognitive step to realise that the file they want to edit is called and it resides inside a directory named after the document.

However, it’s not a big problem as I suspect the power users who do clone the repo and work outside of the CMS will be a bit more technologically advanced, and work out the naming pattern very quickly.

Thanks for implementing the bundles stuff @bep, it worked brilliantly and definitely will make sense for a lot of use cases.