¶ Introduction
While Hugo is a great static site generator, it can sometimes be difficult to set it up to use Atom feeds instead of RSS feeds. Here’s how to do it.
¶ Configuring Hugo
Add this bit of configuration to your config.toml
.
NOTE: (Site.)author.name
is required for the template to generate a valid Atom 1.0 Feed.
NOTE: You might want to modify the outputs
section if you want to include RSS and/or other output formats. Here’s a link to the relevant Hugo documentation.
[author]
name = "John Doe"
[mediaTypes."application/atom+xml"]
suffixes = ["atom"]
[outputFormats.ATOM]
name = "ATOM"
mediaType = "application/atom+xml"
baseName = "feed"
rel = "alternate"
isPlainText = false
isHTML = false
permalinkable = false
[outputs]
home = ["HTML", "ATOM"]
section = ["HTML", "ATOM"]
taxonomy = ["HTML", "ATOM"]
term = ["HTML", "ATOM"]
¶ Adding the Template
Add the following template as layouts/_default/list.atom
:
{{ printf `<?xml version="1.0" encoding="utf-8"?>` | safeHTML }}
{{/* ref: https://validator.w3.org/feed/docs/atom.html */}}
<feed
xmlns="http://www.w3.org/2005/Atom"
{{ with site.LanguageCode }}xml:lang="{{ . }}"{{ end }}>
<generator uri="https://gohugo.io/" version="{{ hugo.Version }}">
Hugo
</generator>
{{- $title := site.Title -}}
{{- with .Title -}}
{{- if (not (eq . site.Title)) -}}
{{- $title = printf `%s %s %s` . (i18n "feed_title_on" | default "on") site.Title -}}
{{- end -}}
{{- end -}}
{{ printf `<title type="html"><![CDATA[%s]]></title>` $title | safeHTML }}
{{ $output_formats := .OutputFormats }}
{{ range $output_formats -}}
{{- $rel := (or (and (eq "atom" (.Name | lower)) "self") "alternate") -}}
{{ with $output_formats.Get .Name }}
{{ printf `<link href=%q rel=%q type=%q title=%q />` .Permalink $rel .MediaType.Type .Name | safeHTML }}
{{- end -}}
{{- end }}
<updated>{{ now.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</updated>
{{ with site.Author.name -}}
<author>
<name>{{ . }}</name>
{{ with site.Author.email }}
<email>{{ . }}</email>
{{ end -}}
</author>
{{- end }}
{{ with site.Params.id }}
<id>{{ . | plainify }}</id>
{{ else }}
<id>{{ .Permalink }}</id>
{{ end }}
{{- $limit := (cond (le site.Config.Services.RSS.Limit 0) 65536 site.Config.Services.RSS.Limit) }}
{{- $pages := .Pages -}}
{{/* Remove the pages that have the disable_feed parameter set to true. */}}
{{- $pages = where $pages ".Params.disable_feed" "!=" true -}}
{{/* Remove the pages that have the unlisted parameter set to true. */}}
{{- $pages = where $pages ".Params.unlisted" "!=" true -}}
{{- range first $limit $pages }}
{{ $page := . }}
<entry>
{{ printf `<title type="html"><![CDATA[%s]]></title>` .Title | safeHTML }}
<link href="{{ .Permalink }}" rel="alternate" type="text/html" />
{{- range first 5 (site.RegularPages.Related .) }}
<link
href="{{ .Permalink }}"
rel="related"
type="text/html"
title="{{ .Title }}" />
{{- end }}
{{ with .Params.id }}
<id>{{ . | plainify }}</id>
{{ else }}
<id>{{ .Permalink }}</id>
{{ end }}
{{ with .Params.author -}}
{{- range . -}}
<!-- Assuming the author front-matter to be a list -->
<author>
<name>{{ . }}</name>
</author>
{{- end -}}
{{- end }}
<published>{{ .Date.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</published>
<updated>{{ .Lastmod.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</updated>
{{ $description1 := .Description | default "" }}
{{ $description := (cond (eq "" $description1) "" (printf "<blockquote>%s</blockquote>" ($description1 | markdownify))) }}
{{ printf `<content type="html"><![CDATA[%s%s]]></content>` $description .Content | safeHTML }}
{{ with site.Taxonomies }}
{{ range $taxo,$_ := . }}
<!-- Defaults taxos: "tags", "categories" -->
{{ with $page.Param $taxo }}
{{ $taxo_list := . }}
<!-- $taxo_list will be the tags/categories list -->
{{ with site.GetPage (printf "/%s" $taxo) }}
{{ $taxonomy_page := . }}
{{ range $taxo_list }}
<!-- Below, assuming pretty URLs -->
<category
scheme="{{ printf "%s%s" $taxonomy_page.Permalink (. | urlize) }}"
term="{{ (. | urlize) }}"
label="{{ . }}" />
{{ end }}
{{ end }}
{{ end }}
{{ end }}
{{ end }}
</entry>
{{ end }}
</feed>
¶ Generated Feeds
- A main
/feed.atom
feed - A per taxonomy (eg. tags, categories)
/[taxonomy]/feed.atom
feed - A per term
/[taxonomy]/[term]/feed.atom
feed - A per section
/[section]/feed.atom
feed