Markdown-style images with full path when baseurl includes subdirectory

support
1

Hi, I might have hit an edge-case that I can’t find out how to resolve when using images. Here’s what I’m trying to accomplish for our documentation site:

  1. I have a bunch of screenshots in leaf bundles (like content/a/image.jpg)
  2. I’d like to include them in the content, preferably using markdown-style, like ![](/a/image.jpg)
  3. I’d like to use the full path, because sometimes I re-use content snippets, so can’t use relative paths
  4. Some of the images should be included in multiple content files (like in content/b/index.md includes ![](/a/image.jpg) as well)
  5. The baseurl includes a subdirectory.

This doesn’t work now, if I reference a non-local image with project-absolute path the links are broken. (They work when using top-level baseurls.) I’ve tried enabling the default render hooks, but still no dice.

One workaround that works is to place such images under the assets directory, but if possible I’d keep them in the relevant content folders.

Suggestions are welcome.

I’ve created a minimal repo that shows the issue: GitHub - fekete-robert/hugo-issue-fullpath-images
(This uses the ananke theme from the hugo quickstart instead of docsy that we use in production, but I don’t think it’s relevant.)
You can build it with
hugo serve --baseURL="http://localhost/docs/" -O then click on Page a

2

Images related to a single page should be placed in a page bundle:

content/
├── posts/
│   ├── post-1/
│   │   ├── c.jpg  <-- page resource
│   │   ├── d.jpg  <-- page resource
│   │   └── index.md
│   ├── post-2.md
│   └── _index.md
└── _index.md

Images that can be used anywhere on the site should be placed in the assets directory:

assets/
└── images/
    ├── a.jpg  <-- global resource
    └── b.jpg  <-- global resource

To make this approach work with Markdown image destinations, enable Hugo’s embedded link and image render hooks in your site configuration:

[markup.goldmark.renderHooks.image]
enableDefault = true

[markup.goldmark.renderHooks.link]
enableDefault = true

The content/posts/post-1/index.md file would look something like this:

![a kitten](images/a.jpg) 

![another kitten](c.jpg)

Note that Hugo’s embedded link and image render hooks are automatically enabled for multilingual single-host sites.

Working example:

git clone --single-branch -b hugo-forum-topic-52487 https://github.com/jmooring/hugo-testing hugo-forum-topic-52487
cd hugo-forum-topic-52487
hugo server

This approach, which in my view should be used on every Hugo site[1], satisfies #1, #2, #3, and #5 in your initial post. Images that are referenced in two or more content files must be placed in the assets directory. In addition to being a technical requirement, this prevents content and site authors from inadvertently breaking image links by doing things like:

  • Deleting an image from the Page A bundle because they don’t know or remember that it is also used in Page B
  • Making an image from the Page A bundle inaccessible from other pages by setting draft = true, setting a future publishing date, setting an expiry date, deleting the bundle, etc.

  1. As noted above, we automatically enable the embedded link and render hooks for multilingual single-host sites. ↩︎

1 Like
3

Many thanks for your help!

4

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