CONTENT MANAGEMENT

Content adapters

New in v0.126.0

Overview

A content adapter is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.

Unlike templates that reside in the layouts directory, content adapters reside in the content directory, no more than one per directory per language. When a content adapter creates a page, the page’s logical path will be relative to the content adapter.

content/
├── articles/
│   ├── _index.md
│   ├── article-1.md
│   └── article-2.md
├── books/
│   ├── _content.gotmpl  <-- content adapter
│   └── _index.md
└── films/
    ├── _content.gotmpl  <-- content adapter
    └── _index.md

Each content adapter is named _content.gotmpl and uses the same syntax as templates in the layouts directory. You can use any of the template functions within a content adapter, as well as the methods described below.

Methods

Use these methods within a content adapter.

AddPage

Adds a page to the site.

content/books/_content.gotmpl
{{ $content := dict
  "mediaType" "text/markdown"
  "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
}}
{{ $page := dict
  "content" $content
  "kind" "page"
  "path" "the-hunchback-of-notre-dame"
  "title" "The Hunchback of Notre Dame"
}}
{{ .AddPage $page }}
AddResource

Adds a page resource to the site.

content/books/_content.gotmpl
{{ with resources.Get "images/a.jpg" }}
  {{ $content := dict
    "mediaType" .MediaType.Type
    "value" .
  }}
  {{ $resource := dict
    "content" $content
    "path" "the-hunchback-of-notre-dame/cover.jpg"
  }}
  {{ $.AddResource $resource }}
{{ end }}

Then retrieve the new page resource with something like:

layouts/_default/single.html
{{ with .Resources.Get "cover.jpg" }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
Site

Returns the Site to which the pages will be added.

content/books/_content.gotmpl
{{ .Site.Title }}
Store

Returns a persistent “scratch pad” to store and manipulate data. The main use case for this is to transfer values between executions when EnableAllLanguages is set. See examples.

content/books/_content.gotmpl
{{ .Store.Set "key" "value" }}
{{ .Store.Get "key" }}
EnableAllLanguages

By default, Hugo executes the content adapter for the language defined by the _content.gotmpl file . Use this method to activate the content adapter for all languages.

content/books/_content.gotmpl
{{ .EnableAllLanguages }}
{{ $content := dict
  "mediaType" "text/markdown"
  "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
}}
{{ $page := dict
  "content" $content
  "kind" "page"
  "path" "the-hunchback-of-notre-dame"
  "title" "The Hunchback of Notre Dame"
}}
{{ .AddPage $page }}

Page map

Set any front matter field in the map passed to the AddPage method, excluding markup. Instead of setting the markup field, specify the content.mediaType as described below.

This table describes the fields most commonly passed to the AddPage method.

Key Description Required
content.mediaType The content media type. Default is text/markdown. See content formats for examples.  
content.value The content value as a string.  
dates.date The page creation date as a time.Time value.  
dates.expiryDate The page expiry date as a time.Time value.  
dates.lastmod The page last modification date as a time.Time value.  
dates.publishDate The page publication date as a time.Time value.  
kind The page kind. Default is page.  
params A map of page parameters.  
path The page’s logical path relative to the content adapter. Do not include a leading slash or file extension. ✔️
title The page title.  

Resource map

Construct the map passed to the AddResource method using the fields below.

Key Description Required
content.mediaType The content media type. ✔️
content.value The content value as a string or resource. ✔️
name The resource name.  
params A map of resource parameters.  
path The resources’s logical path relative to the content adapter. Do not include a leading slash. ✔️
title The resource title.  

Example

Create pages from remote data, where each page represents a book review.

Step 1
Create the content structure.
content/
└── books/
    ├── _content.gotmpl  <-- content adapter
    └── _index.md
Step 2
Inspect the remote data to determine how to map key-value pairs to front matter fields.

https://gohugo.io/shared/examples/data/books.json

Step 3
Create the content adapter.
content/books/_content.gotmpl
{{/* Get remote data. */}}
{{ $data := dict }}
{{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
{{ with resources.GetRemote $url }}
  {{ with .Err }}
    {{ errorf "Unable to get remote resource %s: %s" $url . }}
  {{ else }}
    {{ $data = . | transform.Unmarshal }}
  {{ end }}
{{ else }}
  {{ errorf "Unable to get remote resource %s" $url }}
{{ end }}

{{/* Add pages and page resources. */}}
{{ range $data }}

  {{/* Add page. */}}
  {{ $content := dict "mediaType" "text/markdown" "value" .summary }}
  {{ $dates := dict "date" (time.AsTime .date) }}
  {{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }}
  {{ $page := dict
    "content" $content
    "dates" $dates
    "kind" "page"
    "params" $params
    "path" .title
    "title" .title
  }}
  {{ $.AddPage $page }}

  {{/* Add page resource. */}}
  {{ $item := . }}
  {{ with $url := $item.cover }}
    {{ with resources.GetRemote $url }}
      {{ with .Err }}
        {{ errorf "Unable to get remote resource %s: %s" $url . }}
      {{ else }}
        {{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
        {{ $params := dict "alt" $item.title }}
        {{ $resource := dict
          "content" $content
          "params" $params
          "path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
        }}
        {{ $.AddResource $resource }}
      {{ end }}
    {{ else }}
      {{ errorf "Unable to get remote resource %s" $url }}
    {{ end }}
  {{ end }}

{{ end }}
Step 4
Create a single template to render each book review.
layouts/books/single.html
{{ define "main" }}
  <h1>{{ .Title }}</h1>

  {{ with .Resources.GetMatch "cover.*" }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ .Params.alt }}">
  {{ end }}

  <p>Author: {{ .Params.author }}</p>

  <p>
    ISBN: {{ .Params.isbn }}<br>
    Rating: {{ .Params.rating }}<br>
    Review date: {{ .Date | time.Format ":date_long" }}
  </p>

  {{ with .GetTerms "tags" }}
    <p>Tags:</p>
    <ul>
      {{ range . }}
        <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
      {{ end }}
    </ul>
  {{ end }}

  {{ .Content }}
{{ end }}

Multilingual sites

With multilingual sites you can:

  1. Create one content adapter for all languages using the EnableAllLanguages method as described above.
  2. Create content adapters unique to each language. See the examples below.

Translations by file name

With this site configuration:

hugo.
      
languages:
  de:
    weight: 2
  en:
    weight: 1

[languages]
  [languages.de]
    weight = 2
  [languages.en]
    weight = 1

{
   "languages": {
      "de": {
         "weight": 2
      },
      "en": {
         "weight": 1
      }
   }
}

Include a language designator in the content adapter’s file name.

content/
└── books/
    ├── _content.de.gotmpl
    ├── _content.en.gotmpl
    ├── _index.de.md
    └── _index.en.md

Translations by content directory

With this site configuration:

hugo.
      
languages:
  de:
    contentDir: content/de
    weight: 2
  en:
    contentDir: content/en
    weight: 1

[languages]
  [languages.de]
    contentDir = 'content/de'
    weight = 2
  [languages.en]
    contentDir = 'content/en'
    weight = 1

{
   "languages": {
      "de": {
         "contentDir": "content/de",
         "weight": 2
      },
      "en": {
         "contentDir": "content/en",
         "weight": 1
      }
   }
}

Create a single content adapter in each directory:

content/
├── de/
│   └── books/
│       ├── _content.gotmpl
│       └── _index.md
└── en/
    └── books/
        ├── _content.gotmpl
        └── _index.md

Page collisions

Two or more pages collide when they have the same publication path. Due to concurrency, the content of the published page is indeterminate. Consider this example:

content/
└── books/
    ├── _content.gotmpl  <-- content adapter
    ├── _index.md
    └── the-hunchback-of-notre-dame.md

If the content adapter also creates books/the-hunchback-of-notre-dame, the content of the published page is indeterminate. You can not define the processing order.

To detect page collisions, use the --printPathWarnings flag when building your site.

Last updated: September 10, 2024: Update content-adapters.md (bfe9cdc3)