Fixing RSS properly

[tlienart]

This (finally) fixes the RSS problems (e.g. #805).

• add _rss folder to FranklinTemplates
• change logic of rss_generator
• help deployment at JuliaGPU.org
• add tests
• add docs

How to use this before the release

In your deploy.yml script put the package spec:

- run: julia --project -e '
            using Pkg; Pkg.add(PackageSpec(name="Franklin", rev="rssfix"));
            using Franklin;
            optimize();'

What changes on the user side

If you had at some point a working RSS feed, this should not require you to do anything special, things should just work (and if they don't, please say so).

One thing is that it is now recommended to explicitly set

generate_rss = true

in your config.md along with the mandatory definition of website_url, website_description (or website_descr) for instance:

generate_rss = true
website_title = "JuliaGPU"
website_descr = "High-performance GPU programming in a high-level language."
website_url = "https://juliagpu.org"

What the changes allow / how to benefit from them

The RSS feed is now fully customisable; it is created by doing:

head * prod(items) * "</channel></rss>"

where head comes from _rss/head.xml a file that you control just like a _layout/* file and which, if you don't have it, is copied from head.xml; likewise the items are generated from _rss/item.xml a file that you control as well, see the default item.xml

• head: the head has access to what's defined in your config.md file, for instance the variables website_description, website_url etc.
• item: the item has access to the scope of the corresponding page if it has a rss variable.

That's about it. You can see an example for JuliaGPU:

• config.md note the few lines defining the general RSS variables
• _rss folder the slightly adjusted RSS template

They use a abstract function which basically sets the rss variable see

• a post
• the definition of abstract observe that it sets the variable rss_description; another, easier way would have been to define that variable explicitly and called {{rss}} in the text 😄

Adding full content to RSS item

There are two fields per RSS item: one is the description which should be a short description of what's on the page and another one is content:encoded which is basically the full content of the page. You are allowed to:

• only set description (and it could be the full content)
• set description + content:encoded

you cannot just set content:encoded.

By default only the description is set, but you can add the full page HTML by adding rss_full_content=true in your config.md (example).

Validating your feed

• https://validator.w3.org/feed/docs/rss2.html
• https://www.rssboard.org/rss-profile (for something that's supposed to be really simple there's a lot of best practices...)