From c4e2a189e985ba8c3b3b7fb4c7ec5e82db460417 Mon Sep 17 00:00:00 2001 From: Robert Kingett Date: Tue, 21 Jul 2026 21:41:12 -0500 Subject: [PATCH] Updated RSS documentation --- content/pages/email-to-rss.mdoc | 8 +++++- content/pages/rss-to-email.mdoc | 50 ++++++++++++++++++++++++--------- 2 files changed, 43 insertions(+), 15 deletions(-) diff --git a/content/pages/email-to-rss.mdoc b/content/pages/email-to-rss.mdoc index 5c9e2c8a..a03d7bae 100644 --- a/content/pages/email-to-rss.mdoc +++ b/content/pages/email-to-rss.mdoc @@ -7,8 +7,14 @@ relatedPages: If you've got web archives turned on, Buttondown automatically exposes an RSS feed based on your newsletter's content. You can find it at `https://buttondown.com/your-username/rss`. -This means subscribers can subscribe to your newsletter via their favorite RSS reader, and you can also use the feed to automatically syndicate your newsletter to other platforms using tools such as [IFTTT](https://ifttt.com/) or [Zapier](https://zapier.com/). +This means subscribers can subscribe to your newsletter [via their favorite RSS reader,](https://en.wikipedia.org/wiki/Comparison_of_feed_aggregators) and you can also use the feed to automatically syndicate your newsletter to other platforms using tools such as [IFTTT](https://ifttt.com/) or [Zapier](https://zapier.com/). By default, Buttondown returns the 30 most recent emails in your feed. If you'd like to change this, you can append a `?count=50` query parameter to the end of the URL to change the number of emails returned. +An example of this `?count=50` URL looks like this. + +https://newsletter.sightlessscribbles.com/rss?count=50 + Buttondown also [tracks RSS subscribers](/rss-subscribers), so you can see how many people are subscribing to your RSS feed. + +[If you are looking for the RSS to email documentation, you can find that here](/rss-to-email/) \ No newline at end of file diff --git a/content/pages/rss-to-email.mdoc b/content/pages/rss-to-email.mdoc index a9248e50..0d5f67ab 100644 --- a/content/pages/rss-to-email.mdoc +++ b/content/pages/rss-to-email.mdoc @@ -45,7 +45,7 @@ You can create an RSS automation in [Settings > Basic > RSS-to-email](https://bu At the moment, you can choose from three different 'cadences' for your RSS automation: -- You can have trigger a new email every time a new item is published in your RSS feed. (Buttondown checks your RSS feed every thirty minutes, so it's not quite instantaneous.) +- You can trigger a new email, drafting or immediate sending, every time a new item is published in your RSS feed. (Buttondown checks your RSS feed every thirty minutes, so it's not quite instantaneous.) - You can trigger a new email every week, on a day and time of your choosing. - You can trigger a new email every month, on a day and time of your choosing. @@ -53,17 +53,16 @@ At the moment, you can choose from three different 'cadences' for your RSS autom ## Choosing a behavior -You can choose from two different behaviors for your RSS automation that trigger according to the above cadence: +You can choose from two different behaviors for your RSS automation that trigger according to the above cadences: -- You can have Buttondown send a new email every time a new item is published in your RSS feed. -- You can have Buttondown create a new draft email every time a new item is published in your RSS feed. +- You can have Buttondown send a new email. This means that, for example, every time a new item is published in your RSS feed, Buttondown instantly sends that email. For the digest cadences, it will send the configured digest on the day and time you specify. +- You can have Buttondown create a new draft email every time a new item is published in your RSS feed. For the digest cadences, it will create a draft for you to send later on the day and time you specify The difference between these two behaviors is that the first will send the email immediately, while the second will create a draft email that you can edit before sending. ## Managing your RSS automation -Things happen; you might have to backfill a number of blog posts and you want to exclude them from your automation or you might want to pause your newsletter -for a few weeks while you're tweaking the feed. Buttondown supports several ways to manage your RSS automation: +Things happen; you might have to backfill a number of blog posts and you want to exclude them from your automation or you might want to pause your newsletter for a few weeks while you're tweaking the feed. Buttondown supports several ways to manage your RSS automation: 1. You can _pause_ the automation, which will prevent any new emails from being sent or drafts from being created. Any items that are detected in your RSS feed will be ignored, and will _not_ be automatically queued up for sending or drafting when you unpause the automation. 2. You can _skip_ individual items in your RSS feed. This will prevent the automation from sending or drafting an email for that item, but will not prevent it from sending or drafting emails for any other items in the feed. This concept only applies if you've set up your automation on a weekly or monthly cadence. @@ -73,8 +72,7 @@ for a few weeks while you're tweaking the feed. Buttondown supports several ways ## How Buttondown parses RSS feeds -RSS is a fairly open-ended spec, and there are a number of implementations that are all correct in different ways. Below is a list of the important fields that Buttondown tries to extract -and how it extracts them, in order: +RSS is a fairly open-ended spec, and there are a number of implementations that are all correct in different ways. Below is a list of the important fields that Buttondown tries to extract and how it extracts them, in order: 1. `title`: Buttondown looks for the `title` field in the RSS item. If it's not found, it looks for the `dc:title` field. If that's not found, it looks for the `description` field. 2. `content`: Buttondown looks for the `content:encoded` field in the RSS item. If it's not found, it looks for the `summary_detail` field. @@ -154,10 +152,34 @@ Here's a similar example, except in Atom 1.0: To populate your email with content relevant to the item in your RSS feed, you'll need to build a template. Buttondown uses [Django's template language](/templating) to render your email. This means that you can use all of the standard Django template tags and filters. -For instance, if you want to send a weekly digest of blog posts, you'd start by iterating over the list of items: +For instance, if you want to send a weekly or monthly digest of blog posts, you'd start by iterating over the list of items: + +Multiple examples are below. This first example displays a list of links to all new items published to the feed. + +```jinja {% process=false %} +We published the following essays this week here on {{ feed.title }}: + +{% for item in items %} + +

[{{ item.title }}

+ +{% endfor %} +``` + +To demonstrate the roundup a different way, this next example showcases a way to have the list of links be an orderd list. + +```jinja {% process=false %} +We published the following essays this month here at {{ feed.title }}: + + +``` + +And finally, if you wanted to include some more detail in your digests, as an example, you would do something like this. ```jinja {% process=false %} -We published the following essays this week: +We published the following essays this week here at {{ feed.title }}: {% for item in items %}

{{ item.title }}

@@ -166,11 +188,11 @@ We published the following essays this week: {% endfor %} ``` -Or if you chose a cadence of "every time" for your RSS feed, you'd just send information on the latest item: - +### As it happens cadence examples. -{% playgroundEmbed initialContent="I just published the following essay (read it online [here]({{ item.url }})):{{ item.content }}" /%} +If you chose a cadence of "every time" for your RSS feed, you'd just send information on the latest item: +{% playgroundEmbed initialContent="I just published the following essay, {{ item.title }}. ([Read it online here]({{ item.url }})):{{ item.content }}" /%} ## Edge cases and esoterica @@ -181,4 +203,4 @@ We're the first to admit that there's a _lot_ of esoteric features and functiona ## FAQs -{% faq /%} +{% faq /%} \ No newline at end of file