How do I reference an image in a page bundle?

I like the idea of page bundles, so for a given page, all the files are in a single directory. From the bundle, I’ve been referencing images in a bundle as

![Stuff](stuff.png "Stuff")

Which works great in the single page created for the bundle, but the image is broken in list output (including the home page) that shows full contents (blog-stuyle). Because of course, the image link is relative to the bundle directory, not to the list page path.

I could use the full path to the bundle URL, but that’s kind of annoying when I change things (like the publication date).

So what is the best practice for referencing images or other assets in a bundle, from the in the bundle or anywhere else?


That’s a known issue.

I solve it by using a custom figure shortcode that I explain here:


Thanks. I spent quite a bit of time searching for a solution yesterday; sorry to see that there isn’t one in Hugo itself (yet). I thought maybe this issue shipped a fix, but sadly I couldn’t figure it out.

Time for me to read up on shortcodes. Thanks!

Thanks for that, @kaushalmodi. I did much the same. Here’s my custome figure shortcode.

This is a known limitation.

My take to this, which I think I think gives much better control of the layout etc., is to not have any markdown images in the summary section.

Instead, create some kind of naming standard (cover.jpg, featured.jpg …); then, in your list templates, check for a presence of this image and create a thumbnail of it in the proper dimensions.

The figure shortcode that I proposed though, is solving that limitation + the issue of showing images when the baseURL has sub-directories (+ the issue of ignoring Markdown in captions).

I know that earlier you were not up with merging the fix related to Markdown rendering in figure captions. But of you review the other changes in that updated shortcode, is it good for merging into the core?

It’s not just summaries. Full-text feeds and list pages have the same issue. Some feed readers don’t even know how to deal with relative links! So I’m happy with my custom figure shortcode based on @kaushalmodi’s, in that it always outputs complete URLs. I only wish I could make shortcode templates for different output formats (e.g., plain text, PDF, whatever).

That should work…?

Yes, please open another PR – this is easier to reason about now that the templates are pulled out into files. But it should not be a “breaking change”.

Done! Now just fixing the white-space change caused test fails…

I made a layouts/shortcodes/figure.text for my “text” output, but it was ignored. I’m pretty sure Hugo compiles everything into HTML, and only looks for .html shortcodes; that’s the only extension mentioned in the docs, too.

I’m pretty sure Hugo compiles everything into HTML, and only looks for .html shortcodes

I’m pretty sure we respect output formats for shortcodes. It wasn’t a trivial implementation, but we have several passing tests for what I call the “AMP use case” – and I have tested it myself:

Oh, it looks like you have to make it name.format.html:


I’ll try making a layouts/shortcodes/figure.text.html. Kind of weird…

Okay, I got it to work, and it wasn’t the name of the file that was the problem. It was that I was using .PreprocessedContent. Once I switched to .Content, it worked. Sadly, though, all my Markdown is converted to HTML. What I need it some what to get at the body of my content after the format-specific shortcode has been applied, but without converting from Markdown to HTML.

By the way, while I was working to make that PR pass the checks, I thought of adding my change that markdownifies the text in caption and attr too… and doing that doesn’t break any test! Once this PR gets approved/merged, I can submit that caption markdownification PR again for your consideration.

(BTW, those checks passed finally! pain points… I mistakenly removed trailing spaces at end of lines which were relevant and when I added some lines, they used spaces instead of tabs… tabs… :disappointed: )