The placeholder for your bot's prefix is [p] in this guide.
All commands are under the main command group of [p]rss.
If you already have a rss feed url to use, great! If you need to find an RSS feed from a website url, use [p]rss find with the url.
Q: I added my feed but I got something that says "Bozo feed" in response.
A: Make sure the link is a real RSS feed, in an Atom or XML standard RSS feed format. The feedparser library that RSS uses can only read and use RSS feeds that conform to standards. Sometimes when adding a new feed, your bot may be blocked by Cloudflare from navigating to the RSS feed and receive a bozo response - there is no handling in the cog to be able to follow or solve Cloudflare captchas or gates.
Q: I used [p]rss find on a website link but it told me "No RSS feeds found in the link provided". I think they do have an RSS feed, what's wrong?
A: The rss find command searches the page for any links in the website's HTML where the RSS feed is properly called out, to Atom 1.0 or RSS 2.0 specifications. If the command can't find the feed, maybe approach the site owners to ask for their feeds to identify the feed as application/rss+xml, application/atom+xml, text/xml, or application/rdf+xml for the link tag for the feed.
Add the RSS feed, giving it a name you can refer to later. I'm using test in this example.
Use [p]rss viewtags with the feed name to view a small content preview of all template tags on the most recent post.
The default template of every feed is a simple embed with the feed entry title, the url if present, and the date of the entry.
If you wish to have a simple link post with a title where Discord can auto-unfurl the url, if possible, you only need to toggle off the embed display with [p]rss embed toggle and the feed name.
Preview your changes at any time with [p]rss force.
For the rest of these examples and explaination, I have toggled the test feed back to using an embed, with [p]rss embed toggle.
Now let's explore the feed tags present on the feed, so we can modify the way the feed posts look.
Use [p]rss listtags to display the feed tags.
Templates can include any of these placeholder values, which are prefixed with $. Not all feeds will have all of these placeholder values shown - they can vary from feed to feed and even from post to post on the same feed. Templates can also use the same Markdown formatting that you can use natively in Discord messages, like \n for a line return, ** for bold, etc.
Any tag with plaintext in its name is usually a cleaned or unpacked version of the parent tag it was generated from. For example, in our test feed here, there is a $summary_detail html-containing tag that also has a $summary_detail_plaintext version. If we use the summary detail in our template, we will want to choose the plaintext version.
But what's in that $summary_detail_plaintext tag? Let's see...
Well, this looks good to me on the information I want on these feed posts - let's add the title and the link back.
I used [p]rss template test **$title**\n$link\n\n$summary_detail_plaintext here, giving a bold title with line returns for the link and the summary.
Unfortunately, there are no images to use in these template tags on this test as there are no $content_image tags listed in [p]rss listtags nor does $media_content or the plaintext version of that tag have any image urls. If the post display needed an image preview, we would need to set this feed to display with the embed off, and with a link included, so that Discord can display it if the site is supported.
The $media_content tag, $media_url tag, or any other $media_-prefixed tag usually holds non-image content. This can include and is not limited to video links and audio links. Rarely, there will be an image url in $media_content or $media_url tags, but it should not be the case if the feed or site owner is tagging the feed elements or html elements properly.
Image tags are usually named $content_image01 or similar, where every image url found in the feed post adds 1 to the name value. For example the second image url gathered from the feed post would be named $content_image02 if it was present in [p]rss listtags. Rarely, an image url might be found under the $links_plaintext tag, if present.
Let's make another test feed that has an image to use.
There is a $media_thumbnail_plaintext and a $links_plaintext01 here. Let's see what they contain.
Looks like an image url for the first and a link to the commit on the feed. Let's give it a real template and set the $media_thumbnail_plaintext tag as the embed image.
I used [p]rss template aikaterna-cogs aikaterna-cogs\nAuthor: $author\n[$content_plaintext01]($link). Note the combination of a template tag with a link - you can use [text](url) formatting in an embed with text-containing template tags.
Let's set the embed thumbnail with the [p]rss embed thumbnail command. You can also use [p]rss embed image to set the large embed image to a tag instead of the embed thumbnail.
You can set different image template tags to be the main embed image and the embed thumbnail.
And that's it! You only need to add your feed and customize it with your template and RSS will check the feed every 5 minutes or so. The hardest part is creating a template you like.
RSS qualifies a new post based on the published time and updated time of the feed. Some sites update the updated time of the feed without updating content. This makes the RSS cog "double post" or even continuously post the same post. Use [p]rss parse to be able to configure the RSS cog to use the published_parsed feed tag, and stop multi-posting.
Sometimes, when a feed is set up to RSS standards and specifications, tags are included per feed post that provide content filtering. You can check if your feed includes these tags by using [p]rss listtags and seeing if there are $tags or similar.
This feed has tags! Let's see what some examples of their tags may be. Alternatively, maybe the site lists their RSS post tags elsewhere as a post tag preview may not include all tags in use on the site.
Tag filtering is only an allow list. These tag names are case insensitive, you cannot have differing tags like True Crime vs. true crime - they will be processed the same way.
There are other features of RSS to explore like:
[p]rss embed color - changing the embed color bar if you have an embedded post template
[p]rss limit - limit the amount of characters used per post, but note that this is for the whole template, all template tags combined
[p]rss list or [p]rss listall - list rss feeds in the current channel or all feeds on the Discord server
[p]rss showtemplate - in case you forgot what you used for a feed's template and you would like to use it elsewhere