Markdown-style images with full path when baseurl includes subdirectory

support
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