Where to place image files when using the Markdown content format

tips & tricks
1

Background

When reviewing support requests on this forum, we identify trends—the most frequent problems or questions. These trends represent opportunities for improvement, either in documentation or code.

For example, a common mistake by new users is the placement of an index.md file instead of an _index.md file in the content root. This results in indeterminate behavior, a not-so-great user experience, and yet another support request. Although addressed in documentation for many years, we recently addressed this in the code itself by emitting an ignorable warning, which lets users know about the problem and how to fix it.

The result is a better user experience and fewer support requests.

Resolution of Markdown link and image destinations

Another common problem is proper resolution of Markdown link and image destinations. Although there are several conditions under which link and image destinations are improperly resolved, serving a site from a subdirectory is perhaps the most common. For example, project sites hosted on GitHub Pages are served from a subdirectory (e.g., https://user.github.io/project/).

We addressed this in code with the introduction of the embedded link and image render hooks in v0.123.0. These render hooks are automatically enabled for multilingual single-host sites, but must be manually enabled for monolingual sites and multilingual multi-host sites. Regardless of how these render hooks are enabled, the location of image files is critical.

Where to place image files

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

To include these images in Markdown:

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

![another kitten](c.jpg)

Notes

1) The embedded link and image render hooks are automatically enabled for multilingual single-host sites, provided they are not overridden by project/theme/module hooks.

2) You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration:

[[module.mounts]]
source = 'assets'
target = 'assets'

[[module.mounts]]
source = 'static'
target = 'assets'

3) Hugo’s embedded figure shortcode uses the same resolution logic as the embedded image render hook.

4) This configuration and approach also ensures proper resolution of link destinations for other resource types such as PDF files.

5) A representative sampling of related support requests: 52487, 52537, 52801, 52897, 53062, 53722, 54142, 54803, 54803, and many, many more.

6) Portions of this tips & tricks post will be added to the documentation in the near future.

6 Likes