reivilibre/mirror-zola
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
mirror-zola/docs/content/documentation/templates/feeds/index.md
LunarEclipse363 c054ed1b10 Added support for multiple feeds (i.e. generating both Atom and RSS) (#2477) 
* Added support for multiple feeds

* Implemented backwards-compatibility for feed config

* Added a test for feed config backwards-compat, fixed bugs

- Fixed language config merge bug found by a test
- Adjusted two existing tests to fully check stuff related to multiple feeds
- Added a new test for backwards-compatibility of the changes
- Fixed bugs found by the newly added test

* Renamed MightBeSingle to SingleOrVec

* Made the multiple feeds config changes "loudly" backwards-incompatible

* added #[serde(deny_unknown_fields)] to front-matter, fixed problems this found in tests
2024-06-20 23:15:24 +02:00

4.3 KiB
Raw Permalink Blame History

+++ title = "Feeds" weight = 50 aliases = ["/documentation/templates/rss/"] +++

If the site config.toml file sets generate_feeds = true, then Zola will generate feed files for the site, named according to the feed_filenames setting in config.toml, which defaults to atom.xml. Given the feed filename atom.xml, the generated file will live at base_url/atom.xml, based upon the atom.xml file in the templates directory, or the built-in Atom template.

feed_filenames can be set to any value, but built-in templates are provided for atom.xml (in the preferred Atom 1.0 format), and rss.xml (in the RSS 2.0 format). If you choose a different filename (e.g. feed.xml), you will need to provide a template yourself.

In case you want to extend, or modify, the built-in templates, you can get a copy from the source code here and place it in the templates/ directory with the appropriate name. You can check the documentation for the specifications for Atom 1.0 and RSS 2.0 in W3C Feed Validation Service.

Only pages with a date will be available.

The author in the feed is set as

  • The first author in authors set in the front matter
  • If that is not present it falls back to the author in the Configuration
  • If that is also not preset it is set to Unknown.

Note that atom.xml and rss.xml require different formats for specifying the author. According to RFC 4287 atom.xml requires the author's name, for example "John Doe". While according to the RSS 2.0 Specification the email address is required, and the name optionally included, for example "lawyer@boyer.net" or "lawyer@boyer.net (Lawyer Boyer)".

The feed template gets five variables:

  • config: the site config
  • feed_url: the full url to that specific feed
  • last_updated: the most recent updated or date field of any post
  • pages: see page variables for a detailed description of what this contains
  • lang: the language code that applies to all of the pages in the feed, if the site is multilingual, or config.default_language if it is not

Feeds for taxonomy terms get two more variables, using types from the taxonomies templates:

  • taxonomy: of type TaxonomyConfig
  • term: of type TaxonomyTerm, but without term.pages (use pages instead)

You can also enable separate feeds for each section by setting the generate_feeds variable to true in the respective section's front matter. Section feeds will use the same template as indicated in the config.toml file. Section feeds, in addition to the five feed template variables, get the section variable from the section template.

Enable feed autodiscovery allows feed readers and browsers to notify user about a RSS or Atom feed available on your web site. So it is easier for user to subscribe. As an example this is how it looks like using Firefox Livemarks addon.

RSS feed autodiscovery example.

You can enable posts autodiscovery modifying your blog base.html template adding the following code in between the <head> tags.

{% block rss %}
  <link rel="alternate" type="application/rss+xml" title="RSS" href="{{/* get_url(path="rss.xml", trailing_slash=false) */}}">
{% endblock %}

You can as well use an Atom feed using type="application/atom+xml" and path="atom.xml".

All pages on your site will refer to your post feed.

In order to enable the tag feeds as well, you can overload the block rss using the following code in your tags/single.html template.

{% block rss %}
  {% set rss_path = "tags/" ~ term.name ~ "/rss.xml" %}
  <link rel="alternate" type="application/rss+xml" title="RSS" href="{{/* get_url(path=rss_path, trailing_slash=false) */}}">
{% endblock rss %}

Each tag page will refer to it's dedicated feed.