Resource Organization

This theme processes resources (like images) from all kinds of places: Local, global, or remote. Associated parameters to specify processing and layout options always need to be set locally.

Hugo offers three direct ways to access resources:

Page specific (local)

We can store files in the same folder as the Markdown content and include them with a minimal relative path. We have to register these resources in the frontmatter if we need additional parameters to manipulate them.

This native Hugo concept has one big advantage: The content is self-sufficient and may be reused in other sites simply by cloning the complete folder with the Markdown content and its resources.

Site-wide (global)

We can store them in the assets folder and use them everywhere. The favorite icon in the base template of a site is an example of this use case. Global storage can also be a good choice for repeatedly needed material in our Markdown content.

Remote

Resources may be retrieved via URL or API. The provider could be a separate image server or a more complex service. Hugo stores the data from a remote server in a local cache to avoid repeated requests.

Remote resources may slow down a build considerably when an external service is (temporarily) not available.

Page-specific local resources

When we place our Markdown content file in a separate folder we automatically create a page bundle and can store resource files in the same folder (and subfolders). We can include those files with their relative path directly in our content.

We can also register them in the frontmatter under a new name in a special list under the resources key:

1
2
3

resources:
  - src: image_filename.jpg
    name: image

This is an example of a minimal entry in the resources list. The dash marks the beginning of the list entry followed by the source path and the new name. There are two important rules:

1. We can register every file in a page bundle only once.

2. We cannot include a resource file under its original name anymore.

The advantage we get from this simple entry is the short identifier instead of the long filename. This is the usual way to specify a featured image: Copy the file into the page bundle and name it featured.

Registered resources offer many more possibilities with their optional params section for additional parameters:

1
2
3
4
5
6
7
8
9

resources:
  - src: alexander-grey-tn57JI3CewI-unsplash.jpg
    name: files
    params:
      alt: A pile of files
      ratio: 1.5
      zoom: 1.75
      caption: This is the same image as the featured one. But the image has 
been cropped to the ratio of 3:2 and zoomed in with a factor of 1.75.

The theme can process a bunch of them for all Markdown images.

Site-wide (global) resources

We can include these files directly with their path relative to the assets folder.

In case we need to store them elsewhere in folders (local or remote), we can let Hugo mount these into assets.

Remote resources

We can include remote resources directly with their absolute uniform resource locators (URLs) including optional query parameters.

Global and remote resources with additional parameters

To associate global files with extra parameters we need to create a local data file (YAML, TOML, or JSON) with our global or remote resource as src and add the other parameters. Then we reference this data file as if it would be the resource.

![Global image](global.yaml) for example generates an image referenced in the data file global.yaml:

src: img/tiger/alicia-chong-jYM-AV5RRag-unsplash.jpg
caption: This tiger is stored in the assets folder. The attribution here is 
extracted from the filename, but we can also add one manually.

Fallback: resources from related page bundles

There is also the option to reuse local page resources as a fallback. If a resource can’t be found the theme uses the partial mod-resource/func/helper/page-fallback.html to look elsewhere. We can overwrite this partial with one in the same relative path to our projects layouts/partials folder.

Default

The theme falls back to resources from the parent folder by default.

Alternative example

This documentation project falls back to related taxonomies and parent pages. This also allows the use of resources from taxonomy terms in simple pages.

The fallback search happens in the following lookup order:

1. Tags of the page
2. Categories of the page
3. Parent of the page
4. Parents parent …

If there are more resources with the same name (like “featured”) on a related type of page, then the first match wins.