Relative Markdown Links for images

I found this post very helpful in getting my Markdown relative links to correctly link to other markdown files in my /posts directory. I expected the following in layouts/_default/_markup/render-image.html to make it so images would render

<p class="md__image">

<img src="{{ (.Page.GetPage .Destination).RelPermalink | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />


But instead I get some sort of error, and image links render as <img src=unknown alt="...

How can this be fixed, so that I can link, for example, an image in /content/posts/vacationpictures from a file in /content/posts/

I do not want to put my pictures in the static folder - when I do that they don’t render in Github or VSCode.

1 Like

Did you try safeHTMLAttr instead of safeURL? I think the issue for safeURL is, that RelPermalink has no protocol and domain in the beginning which makes it potentially a string instead of an URL.

On the other side: Where do you get .Destination from? Is it maybe, ehm, “unknown”?

Well I get .Destination from the Hugo documentation I was just trying to to the analogous thing for images to what @pavelbinar did for links, replacing .Destination with (.Page.GetPage .Destination).RelPermalink

It seems to render images in the static directory fine with with .Destination with both safeHTMLAttr and safeURL, but neither fix the problem with not being able to display images with relative links.

1 Like

Hi @BoltonBailey,

did you finally find a solution with images and relative paths?

Note that I know about page bundles, but I don’t want to rename all my markdown files in
For portability, I also don’t want to use shortcodes.

More precisely, I want to stick to this structure:

- article-about-stuff/image.jpg

and use a Markdown like this:


@iaeiou I believe the main branch (which is currently in beta) of my link-handling repo has this resolved.

It’s probably more complex than you want, but maybe you can learn from it?

1 Like

I wondered why my articles in folders (I guess these are the page bundles?) were not working with this structure until I renamed the file to For portability, Hugo should consider supporting this structure.

1 Like

Check out this example repo by @-bep: GitHub - bep/portable-hugo-links: A test repo to test out the new Markdown Render Hooks in Hugo 0.62.0

You can get portable Markdown content + images by using

  1. Hugo Mounts (needs the Hugo Modules feature, and so you need to have a recent version of go installed on your system. Installing go is simply downloading and extracting its installation archive file in your $HOME/go.). See the mounts config in the config.toml in that repo.
  • You can mount any of the Hugo components like content and assets from any directory in the repo to the location that Hugo expects. So you can have images referenced in your Markdown content be mounted to the global resources directory assets i.e. You don’t have to use the leaf bundle approach and rename the content files to
  1. Use render-image.html hooks. See its example here in that repo.
  • These hooks allow you to have Markdown style image links in your content. The hooks can do the lookup of referenced images using the Hugo resources API (because the mounts above mounted all your images in the resources directory assets).

That’s the gist of how this works. But read up more on Hugo Mounts and image render hooks in the Hugo documentation, and clone that example repo and tweak it to better understand how these features work together.


I reread the following to notes:

and I’m not sure what you want is actually possible. If you made articles-about-stuff a directory and moved to articles-about-stuff/ with the image.jpg in articles-about-stuff/ leaf bundle it would definitely work.

The specific output structure you mention may require a specific input structure. I think this is a case where I need to defer to @jmooring