Page resources

Page resources are only accessible from page bundles, those directories with index.md or _index.md files at their root. Page resources are only available to the page with which they are bundled.

In this example, first-post is a page bundle with access to 10 page resources including audio, data, documents, images, and video. Although second-post is also a page bundle, it has no page resources and is unable to directly access the page resources associated with first-post.

content
└── post
    ├── first-post
    │   ├── images
    │   │   ├── a.jpg
    │   │   ├── b.jpg
    │   │   └── c.jpg
    │   ├── index.md (root of page bundle)
    │   ├── latest.html
    │   ├── manual.json
    │   ├── notice.md
    │   ├── office.mp3
    │   ├── pocket.mp4
    │   ├── rating.pdf
    │   └── safety.txt
    └── second-post
        └── index.md (root of page bundle)

Examples #

Use any of these methods on a Page object to capture page resources:

[Resources.ByType]
[Resources.Get]
[Resources.GetMatch]
[Resources.Match]

Once you have captured a resource, use any of the applicable [Resource] methods to return a value or perform an action.

The following examples assume this content structure:

content/
└── example/
    ├── data/
    │  └── books.json   <-- page resource
    ├── images/
    │  ├── a.jpg        <-- page resource
    │  └── b.jpg        <-- page resource
    ├── snippets/
    │  └── text.md      <-- page resource
    └── index.md

Render a single image, and throw an error if the file does not exist:

{{ $path := "images/a.jpg" }}
{{ with .Resources.Get $path }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ else }}
  {{ errorf "Unable to get page resource %q" $path }}
{{ end }}

Render all images, resized to 300 px wide:

{{ range .Resources.ByType "image" }}
  {{ with .Resize "300x" }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

Render the markdown snippet:

{{ with .Resources.Get "snippets/text.md" }}
  {{ .Content }}
{{ end }}

List the titles in the data file, and throw an error if the file does not exist.

{{ $path := "data/books.json" }}
{{ with .Resources.Get $path }}
  {{ with . | transform.Unmarshal }}
    <p>Books:</p>
    <ul>
      {{ range . }}
        <li>{{ .title }}</li>
      {{ end }}
    </ul>
  {{ end }}
{{ else }}
  {{ errorf "Unable to get page resource %q" $path }}
{{ end }}

Metadata #

The page resources’ metadata is managed from the corresponding page’s front matter with an array/table parameter named resources. You can batch assign values using wildcards.

name: (string) Sets the value returned in Name.

title: (string) Sets the value returned in Title
params: (map) A map of custom key-value pairs.

Resources metadata example #

content/example.md

---
date: "2018-01-25"
resources:
- name: header
  src: images/sunset.jpg
- params:
    icon: photo
  src: documents/photo_specs.pdf
  title: Photo Specifications
- src: documents/guide.pdf
  title: Instruction Guide
- src: documents/checklist.pdf
  title: Document Checklist
- src: documents/payment.docx
  title: Proof of Payment
- name: pdf-file-:counter
  params:
    icon: pdf
  src: '**.pdf'
- params:
    icon: word
  src: '**.docx'
title: Application
---

+++
date = '2018-01-25'
title = 'Application'
[[resources]]
  name = 'header'
  src = 'images/sunset.jpg'
[[resources]]
  src = 'documents/photo_specs.pdf'
  title = 'Photo Specifications'
  [resources.params]
    icon = 'photo'
[[resources]]
  src = 'documents/guide.pdf'
  title = 'Instruction Guide'
[[resources]]
  src = 'documents/checklist.pdf'
  title = 'Document Checklist'
[[resources]]
  src = 'documents/payment.docx'
  title = 'Proof of Payment'
[[resources]]
  name = 'pdf-file-:counter'
  src = '**.pdf'
  [resources.params]
    icon = 'pdf'
[[resources]]
  src = '**.docx'
  [resources.params]
    icon = 'word'
+++

{
   "date": "2018-01-25",
   "resources": [
      {
         "name": "header",
         "src": "images/sunset.jpg"
      },
      {
         "params": {
            "icon": "photo"
         },
         "src": "documents/photo_specs.pdf",
         "title": "Photo Specifications"
      },
      {
         "src": "documents/guide.pdf",
         "title": "Instruction Guide"
      },
      {
         "src": "documents/checklist.pdf",
         "title": "Document Checklist"
      },
      {
         "src": "documents/payment.docx",
         "title": "Proof of Payment"
      },
      {
         "name": "pdf-file-:counter",
         "params": {
            "icon": "pdf"
         },
         "src": "**.pdf"
      },
      {
         "params": {
            "icon": "word"
         },
         "src": "**.docx"
      }
   ],
   "title": "Application"
}

From the example above:

sunset.jpg will receive a new Name and can now be found with .GetMatch "header".
documents/photo_specs.pdf will get the photo icon.
documents/checklist.pdf, documents/guide.pdf and documents/payment.docx will get Title as set by title.
Every PDF in the bundle except documents/photo_specs.pdf will get the pdf icon.
All PDF files will get a new Name. The name parameter contains a special placeholder :counter, so the Name will be pdf-file-1, pdf-file-2, pdf-file-3.
Every docx in the bundle will receive the word icon.

The `:counter` placeholder in `name` and `title` #

The :counter is a special placeholder recognized in name and title parameters resources.

The counter starts at 1 the first time they are used in either name or title.

For example, if a bundle has the resources photo_specs.pdf, other_specs.pdf, guide.pdf and checklist.pdf, and the front matter has specified the resources as:

content/inspections/engine/index.md

---
resources:
- src: '*specs.pdf'
  title: 'Specification #:counter'
- name: pdf-file-:counter
  src: '**.pdf'
title: Engine inspections
---

+++
title = 'Engine inspections'
[[resources]]
  src = '*specs.pdf'
  title = 'Specification #:counter'
[[resources]]
  name = 'pdf-file-:counter'
  src = '**.pdf'
+++

{
   "resources": [
      {
         "src": "*specs.pdf",
         "title": "Specification #:counter"
      },
      {
         "name": "pdf-file-:counter",
         "src": "**.pdf"
      }
   ],
   "title": "Engine inspections"
}

the Name and Title will be assigned to the resource files as follows:

Resource file	`Name`	`Title`
checklist.pdf	`"pdf-file-1.pdf`	`"checklist.pdf"`
guide.pdf	`"pdf-file-2.pdf`	`"guide.pdf"`
other_specs.pdf	`"pdf-file-3.pdf`	`"Specification #1"`
photo_specs.pdf	`"pdf-file-4.pdf`	`"Specification #2"`

Multilingual #

By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site.

Consider this site configuration:

hugo.

defaultContentLanguage: de
defaultContentLanguageInSubdir: true
languages:
  de:
    languageCode: de-DE
    languageName: Deutsch
    weight: 1
  en:
    languageCode: en-US
    languageName: English
    weight: 2

defaultContentLanguage = 'de'
defaultContentLanguageInSubdir = true
[languages]
  [languages.de]
    languageCode = 'de-DE'
    languageName = 'Deutsch'
    weight = 1
  [languages.en]
    languageCode = 'en-US'
    languageName = 'English'
    weight = 2

{
   "defaultContentLanguage": "de",
   "defaultContentLanguageInSubdir": true,
   "languages": {
      "de": {
         "languageCode": "de-DE",
         "languageName": "Deutsch",
         "weight": 1
      },
      "en": {
         "languageCode": "en-US",
         "languageName": "English",
         "weight": 2
      }
   }
}

And this content:

content/
└── my-bundle/
    ├── a.jpg     <-- shared page resource
    ├── b.jpg     <-- shared page resource
    ├── c.de.jpg
    ├── c.en.jpg
    ├── index.de.md
    └── index.en.md

With v0.122.0 and earlier, Hugo duplicated the shared page resources, creating copies for each language:

public/
├── de/
│   ├── my-bundle/
│   │   ├── a.jpg     <-- shared page resource
│   │   ├── b.jpg     <-- shared page resource
│   │   ├── c.de.jpg
│   │   └── index.html
│   └── index.html
├── en/
│   ├── my-bundle/
│   │   ├── a.jpg     <-- shared page resource (duplicate)
│   │   ├── b.jpg     <-- shared page resource (duplicate)
│   │   ├── c.en.jpg
│   │   └── index.html
│   └── index.html
└── index.html

With v0.123.0 and later, Hugo places the shared resources in the page bundle for the default content language:

public/
├── de/
│   ├── my-bundle/
│   │   ├── a.jpg     <-- shared page resource
│   │   ├── b.jpg     <-- shared page resource
│   │   ├── c.de.jpg
│   │   └── index.html
│   └── index.html
├── en/
│   ├── my-bundle/
│   │   ├── c.en.jpg
│   │   └── index.html
│   └── index.html
└── index.html

This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost.

Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired:

hugo.

markup:
  goldmark:
    duplicateResourceFiles: true

[markup]
  [markup.goldmark]
    duplicateResourceFiles = true

{
   "markup": {
      "goldmark": {
         "duplicateResourceFiles": true
      }
   }
}

Page resources

Use page resources to logically associate assets with a page.

Examples #

Metadata #

Resources metadata example #

The :counter placeholder in name and title #

Multilingual #

The `:counter` placeholder in `name` and `title` #