How to make Hugo (0.20+) generate an Atom feed instead of RSS

README.md

The Hugo static site generator sadly still uses the obsolete and badly standardized RSS format.

Here's how to set it up to generate an Atom feed instead. Pretty much all feed readers which understand RSS also understand Atom, except iTunes, and Atom is a better format.

1. Define an appropriate media type and corresponding output format in config.toml:

    [mediaTypes]
    [mediaTypes."application/atom"]
    suffix = "xml"

    [outputFormats.Atom]
    mediaType = "application/atom"
    baseName = "index"
    isPlainText = false

2. Tell Hugo to produce the home page in Atom and HTML formats, also in config.toml:

    [outputs]
    home = [ "HTML", "Atom" ]

3. Put an index.atom.xml template file in your layouts directory. You can use the attached one as a starting point, don't forget to edit the author element appropriately or make it take the values from your config.

index.atom.xml

<feed xmlns="http://www.w3.org/2005/Atom">
  <title>{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}</title>
  <link rel="self" href="{{ .Permalink }}"/>
  <updated>{{ .Date.Format "2006-01-02T15:04:05-0700" | safeHTML }}</updated>
  <author>
    <name>YOUR NAME HERE</name>
    <email>YOUR EMAIL ADDRESS</email>
    <uri>DEFINITIVE URI OF YOUR WEB SITE</uri>
  </author>
  <id>{{ .Permalink }}</id>
  {{ range first 15 .Data.Pages }}
  <entry>
    <title>{{ .Title }}</title>
    <link rel="alternate" href="{{ .Permalink }}"/>
    <id>{{ .Permalink }}</id>
    <published>{{ .Date.Format "2006-01-02T15:04:05-0700" | safeHTML }}</published>
    <updated>{{ .Lastmod.Format "2006-01-02T15:04:05-0700" | safeHTML }}</updated>
    <summary>{{ .Summary | html }}</summary>
  </entry>
  {{ end }}
</feed>

Thanks for this. The configuration was helpful. I had to make some adjustments to the template to get it to validate.

<feed xmlns="http://www.w3.org/2005/Atom">
  <title>{{ if eq  .Title  .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}{{ end }}</title>
  <link href="{{ .Permalink }}index.xml" rel="self"/>
  <link href="{{ .Permalink }}"/>{{ if not .Date.IsZero }}
  <updated>{{ .Date.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</updated>{{ end }}
  <id>{{ .Permalink }}</id>{{ with .Site.Author.name }}
  <author>
    <name>{{.}}</name>{{ with $.Site.Author.email }}
    <email>{{.}}</email>{{end}}
  </author>{{end}}
  <generator>Hugo -- gohugo.io</generator>{{ range .Data.Pages }}
  <entry>
    {{ `<title type="html"><![CDATA[` | safeHTML }}{{ .Title }}]]></title>
    <link href="{{ .Permalink }}"/>
    <id>{{ .Permalink }}</id>{{ with .Site.Params.Author }}
    <author>
      <name>{{.}}</name>
    </author>{{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>
    {{ `<content type="html"><![CDATA[` | safeHTML }}{{ .Content }}]]></content>
  </entry>{{ end }}
</feed>

Update: I removed the | html part from {{ .Content | html }} because escaping the content caused it to not render properly in my feed reader. The validators complain about the data-lang attributes that are there for syntax highlighting, but I think that's ok.

In case anyone else stumbles on this as I did, I added some updates of my own drawing from Hugo's current RSS template.

{{- $pctx := . -}}
{{- if .IsHome -}}{{ $pctx = .Site }}{{- end -}}
{{- $pages := slice -}}
{{- if or $.IsHome $.IsSection -}}
{{- $pages = $pctx.RegularPages -}}
{{- else -}}
{{- $pages = $pctx.Pages -}}
{{- end -}}
{{- $limit := .Site.Config.Services.RSS.Limit -}}
{{- if ge $limit 1 -}}
{{- $pages = $pages | first $limit -}}
{{- end -}}
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>{{ if eq  .Title  .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}{{ end }}</title>
  <link href="{{ .Permalink }}index.xml" rel="self"/>
  <link href="{{ .Permalink }}"/>{{ if not .Date.IsZero }}
  <updated>{{ .Date.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</updated>{{ end }}
  <id>{{ .Permalink }}</id>{{ with .Site.Author.name }}
  <author>
    <name>{{.}}</name>{{ with $.Site.Author.email }}
    <email>{{.}}</email>{{end}}
  </author>{{end}}
  <generator>Hugo -- gohugo.io</generator>{{ range $pages }}
  <entry>
    {{ `<title type="html"><![CDATA[` | safeHTML }}{{ .Title }}]]></title>
    <link href="{{ .Permalink }}"/>
    <id>{{ .Permalink }}</id>{{ with $.Site.Author.name }} 
    <author>
      <name>{{.}}</name>
    </author>{{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>
    {{ if .Content }}
    {{ `<content type="html"><![CDATA[` | safeHTML }}{{ .Content }}]]></content>
    {{ end }}
  </entry>{{ end }}
</feed>

My configurations:

• https://github.com/alswl/hugo-PaperMod/commit/e31c1a32f6f63b8710011119db8188f8d47ece8d
• alswl/blog.alswl.com@3e7af25

The RSS / Atom feeds are validated by W3C https://validator.w3.org/feed/#validate_by_input .