Confusion regarding image render hooks


I want to display an image which works both in Github preview and in the site. @bep provided an amazing example but in the example the image resides in a page bundle and I want to reuse the image in multiple pages so I want something as some directory in content/.
I came across branch bundles but I guess some changes to the render-image file because the branch bundles are to accessed as regularpages and I am not able to achieve that in the render-image. The image-render uses .Page.Resources to get the image. but that won’t get the ones outside the page bundle.
I also came across headless bundles but again I face problems in rendering the image in the preview properly. And also I don’t know if this is the best practice as compared to having resources.

How should I modify the render-image.html so that for an image contents/images/img.png can be used in a page like blogs/ by something like this -> ![Image](../images/img.png)?

I am very confused as to what is the correct way. Any help is appreciated.


First, what you want should be possible, but you need to create some kind of scheme for yourself:

  1. First look in the current page’s bundle
  2. Then use path.Dir and GetPage to find a headless bundle or similar

Or something like that.

I have updated the example project with a fallback to /images mounted in /assets, which I guess makes sense. It should also be possible to do this with some headless bundle.

Thanks, @bep. I tried using the above workaround. I placed my image in content/images and added source = "content/images" to the config. Now I include the image in my content/blogs/ as ![Image](../images/imgg.png) which successfully previews but fails in the site. If I use ![Image](/images/imgg.png) then it works fine, even without the mount changes but fails to preview.

Is there something I am missing here?

Here is the complete config.toml of my project.

This is my directory structure there is any confusion:


Although I am open to changing the location of the image whichever suits the implementation easily and follows the best practices.


In my example you would mount them below /assets.

Look at my example:

source = "images"
target = "assets/images"

Now my example is a little special, as I have all the folders on top level (to simulate a "non Hugo project), but I assume you can do something like this:

source = "content/images"
target = "assets/images"

Note that I assume the same would be possible with a bundle, but that example would need to wait for another day when I’m less busy. My main point was to demonstrate “fall back lookups”.

Hugo does not support relative paths for assets.
It used to… some ages ago (around v0.16 -if memory serves me right-) but then this was changed for reasons that the previous or current maintainer only know.

The way I’ m doing what you ask is by specifying the full image PATH in the .Destination attribute of the Markdown image…

Hugo publishes image assets globally from withing a Page Bundle.

So if you don’t mind organizing your content in Bundles, then you can do without GetPage and Hugo Modules.

For example a file under

└── example
    └── 1.jpg

Will be available from within its own Page Bundle with both ![alt](1.jpg) as well as ![alt](example/1.jpg)

But from the other pages that reside elsewhere under the contentDir that image will always be available with: ![alt](example/1.jpg)

Of course you will not have an image preview generated with a Markdown editor when you link to a Markdown image as I described above but that is a small price to pay.

You should run hugo server with the --navigateToChanged flag whenever you edit content in Hugo to have instant preview in the browser.

This is how I work in image-heavy projects that I maintain.

I prefer simplicity above all else.

We do. See my example.

Right. I’m sorry. I used the wrong term.

Let me clarify.

As far as I know Hugo does not support relative links to Page Resources residing under the contentDir, hence my answer above.

As you pointed out Hugo does support relative links to image assets that are mounted as Hugo Modules under the assetDir.

However please note that for some of us Hugo Modules are not a viable option due to the Go dependency. Projects that I maintain need to be as portable as possible with minimal installation requirements.

That is why I decided to use Hugo in the first place.

@alexandros I too initially came up with the same idea after seeing @bep’s example. But I want the images to be able to share every where. Also whenever I want to add an image to a file which previously did not have it, I need to re-organize the folder structure which is not so dev-friendly in my opinion (a simple image addition should not have this much effect). And the Github previews are important since it is a documentation site.

Also, I noticed that I forgot to do the necessary changes in render-image.html. After doing them, it works like a charm!!!

Thank you both so much for the discussion. I learnt a lot :smiley:

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.