Note: A German translation of this description is available here. Hinweis: Eine deutsche Übersetzung dieser Beschreibung ist hier verfügbar.
This is a supplementary theme for other Hugo themes that will help to generate web feeds in the formats Atom, RSS 2.0 and the fairly new JSON Feed to allow site visitors to subscribe to the content you create.
A list of major supported features:
- Full multi-language support
- Multi-user support with author profile pages, both on site and page level
- Supports full content and summary, customizable on site and page level
- Featured image support
- Banner image support (JSON Feed only)
- Subtitle support
- Taxonomy support
- Custom URN support for Atom and JSON feed IDs on site and page level
- UTM tracking support
This is what's on the To-Do list right now:
- Table of Contents (TOC) support
- WebSub support
- Provided Feed Formats
- Getting Started
- Deployment
- Built For
- Versioning
- Authors
- License
- Acknowledgments
This is today's default format to consume a web feed and should be what you offer to your visitors and readers.
The default file name for Atom feeds is feed.atom (also see .atom file extension).
This format came up as an idea of Manton Reece and Brent Simmons in 2017 and has seen quite prominent adoption to sites since then.
However, on Wikipedia it is currently only known as "just another type" of data feeds with no relation to be an official web feed format yet. This is why the JSON Feed format is marked as experimental here, especially as visitors need to have a state-of-the-art feed reader1 that is supporting this brand new format. That is why it cannot be the only format offered without risking to loose interest of visitors to subscribe.
The default file name for JSON Feed files is feed.json.
The RSS 2.0 feed will replace the Hugo built-in RSS feed and is extended using several commonly used XML namespaces for enhanced functionality that is almost similar to what an Atom 1.0 feed provides.
However, it is not guaranteed that each and every feed reader will respect those extensions properly. That is why this feed type is marked as legacy and shall only be offered as a fallback to end users (if at all) in case anyone of them is not able to consume the Atom feed.
Also note that there are still some important differences between the two formats, in particular when content is being updated or corrected while a user had already downloaded a version of the feed that contained an earlier version of that particular content.
Using the Hugo Web Feeds theme, the default file name for RSS feeds is automatically changed from index.xml to feed.rss (also see .rss file extension).
As web feeds are not intended for direct consumption without using another piece of software (see news aggregator), Hugo Web Feeds is a supplementary theme that will support other themes by only creating the required additional plain text files.
That means you first need to install and configure a regular Hugo theme that will generate real content structures and HTML pages for your site.
See instructions on the Hugo documentation pages to learn how to do that.
There are basically two ways to include web feeds to your own site or theme:
For easier updates of the Hugo Web Feeds theme component, it is recommended to make use of Git Submodules.
This is how:
git submodule add -b master https://github.com/jpawlowski/hugo-web-feeds.git themes/web-feeds/Now, whenever you clone a fresh copy of your own project's Git repository, you will need to make sure to also check out all submodules in use. This is an example:
git clone --recurse-submodules https://github.com/<USERNAME>/MyProjectAlso note that if you are using multiple branches in your Git repository, this requires special handling to ensure the submodule was properly added to each of it. This also applies whenever you are planning to update the Hugo Web Feeds theme to a newer version (meaning to a different commit ID, actually).
I will not go into more details here. Either use a good Git GUI application or have a look to the Git documentation pages.
If you simply want to go with the current version and don't care about any future update paths or code history, you may simply download a copy of the latest source code to your own project directory:
mkdir -p themes/; curl -fsSL https://github.com/jpawlowski/hugo-web-feeds/archive/master.tar.gz | tar zx -C themes/; mv themes/hugo-web-feeds-master/ themes/web-feeds/This will install the theme to the themes/web-feeds/ folder.
In your site's config.toml file, find the theme = [...] variable and add web-feeds in front of whatever you have in there already:
theme = [ "web-feeds", "my-theme" ]As this is a supplementary theme, it needs to be processed before all other themes so the order is really playing an important role here.
Also note that the variable is now in slice format (see the brackets?). If you had only enabled a single theme before, it might have been a simple key = "value" pair so keep that in mind.
Next, find the [outputs] section to either replace "RSS", or add "Atom" and "JSONFeed" to it:
[outputs]
home = ["HTML", "RSS", "Atom", "JSONFeed"] # optionally remove RSS here
section = ["HTML", "RSS", "Atom", "JSONFeed"] # optionally remove RSS here
taxonomy = ["HTML", "RSS", "Atom", "JSONFeed"] # optionally remove RSS hereUnfortunately Hugo Web Feeds is unable to automatically help you with autodiscovery as HTML rendering must be part of the other theme you are using. There is a generic code snippet for you to add to the layouts/partials/head.html file or wherever your theme as left a way to add some custom code to the HTML <head> element.
{{ partial "feed_header.html" . }}It is a good idea to have your web server configured to send the correct Content-Type HTTP response header when delivering the feed files. This is likewise important for Atom and RSS feed types.
While this might not be necessary for most of the feed readers to work, it plays quite an important role in the user experience when visitors subscribe to your feed. By sending the correct Content-Type information, the browser will be able to look for an application on the persons device that is capable to handle this file type – like a feed reader in our case. That is of course, if the browser was properly supporting this (e.g. Chrome is not) and the local feed reader had actually claimed to be able to handle web feeds.
This however is nothing we can influence. what we can do from our end is to provide the most useful information to the visitor's software in our feed files and when delivering it.
To be able to do all this, your web server needs to know about the the file's MIME type which it usually dereives from the file's extension name for types that it was configured for. This is not possible for .xml file extensions as this only implies that the file was in XML format but not what kind of dialect that content was defined for. This is why we (re)named our feed files feed.atom and feed.rss in the first place.
You may check your web server headers for the respective feed URL either by using the developer functions in your web browser or by using free online services like Cloxy Tools.
For Atom feeds, the Content-Type: line will need to look like this:
Content-Type: application/atom+xml; charset=UTF-8RSS feeds will need to be sent using this Content-Type::
Content-Type: application/rss+xml; charset=UTF-8JSON feeds currently do not have an officially confirmed MIME type. However, based on RFC 6839 and JSON Feed Pull Request #32, this Content-Type: is the most logical to assume:
Content-Type: application/feed+json; charset=UTF-8If this does not look exactly like this (even if the charset setting was missing), you will need to tweak the configuration of your web server. This depends on the software you use. Some examples and hints can be found below.
Add header definitions to your netlify.toml file like this:
[[headers]]
for = "*.atom"
[headers.values]
Content-Type = "application/atom+xml; charset=UTF-8"
[[headers]]
for = "*.rss"
[headers.values]
Content-Type = "application/rss+xml; charset=UTF-8"
[[headers]]
for = "*feed.json"
[headers.values]
Content-Type = "application/feed+json; charset=UTF-8"To learn more about custom headers on Netlify, go to the docs or read this blog post.
Go to read more about the Types directive.
Go to read more about the AddType directive.
Go to read more about the Configuration of MIME Types in IIS 7, Configuring HTTP Response Headers in IIS 7 or Modifying HTTP Response Headers.
- Hugo - The web framework of choice
We use SemVer for versioning. However, the version is only reflected as part of the theme.toml file.
Production and staging versions of this theme are differentiated using branches.
For your production sites, the master branch is what you want to use.
If you want to test some new functionality that you know is still in development, the dev branch is what you are looking for.
For all the branches available, see the branches on this repository.
- Julian Pawlowski - Several extensions and enhancements, RSS 2.0, JSON Feed adoption and WebSub support - hugo-web-feeds
- Kaushal Modi - Initial work for standalone Atom feed - hugo-atom-feed
See also the list of other contributors who participated in this project.
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
- Thank Kaushal Modi for teaching me about Hugo and Go programming syntax and sharing ideas.
- Thank George Cushen for his initial inspiration as part of his awesome Academic theme
- Thank Billie Thompson for her idea to provide a great template and structure for this README file
Footnotes
-
like NetNewsWire, also made by Brent Simmons. ↩