The Guide to Feeds

Overview

This is meant to be a non-comprehensive guide to Feed Generators ("custom feeds" or just "feeds") in Bluesky.

What are feeds?

Feeds are a way to present Bluesky posts to a given user. They can be as straightforward as filtering for keywords or by post author, or as complex as using the follower graph to find friends of friends.

How do feeds generally work?

The canonical example feed generator[1] has two major parts:

• the first part connects to the Bluesky firehose, which is a stream of all events (posts, likes, etc) and saves them to a database
• the second part provides a space to answer the question "which posts are in the X feed?"

[1] https://github.com/bluesky-social/feed-generator

What do feeds have access to?

Every request to a feed generator includes a verifiable token representing the user requesting the feed.

What are the different kinds of feeds?

The following are different methods of serving feeds, which may be combined in various ways.

Based on Keywords

A feed can present posts with text matching certain keywords. A popular variant/subset of this is using emojis, e.g. 🧪, 🌱, or 🤼‍♀️. More powerful text matching will use regular expressions, which are more flexible in their filtering capabilities.

Based on Users (Public List)

The feed presents posts by a certain set of users. Presently there are two ways to collect users: following users, or mute lists.

Based on Users (Private List)

The feed presents posts by a certain set of users, kept in a list that cannot be easily seen by the public. This may be a list in the code, or a list saved in a database. Oftentimes, the list is kept in Decentralized ID (DID) form; see https://atproto.com/guides/identity for more information.

Based on the Requesting User

The feed presents posts based on the requesting user, such as:

• The requesting user's following timeline
• The requesting user's liked posts
• The requesting user's posts, filtering for a certain type: with media, replies, reposts

Based on User Segmentation

The feed presents posts from a segment of users based on the requesting user.

Example: Teams by @retr0-id.translate.goog

Based on Content Metadata (Alt text, Embeds, Labels)

The feed presents posts based on attributes which may or may not be easily seen in the UI.

• Alt text is a user-provided text description for an embedded image
• Embedded links to external websites will have website title, link and description
• Labels are manually or automatically applied to accounts or posts, such as: account is flagged as impersonation, or posts are marked as NSFW

Based on Content (Advanced)

The feed presents posts based on the content itself, using such strategies as:

• Computer Vision (CV), or image detection: dogs, cats, birds
• Language detection

Based on Social Signals

The feed presents posts based on the number of likes, reposts, replies, and/or quotes.

Based on Social Signals and Social Graph

Since the feed has access to the requesting user, and the social graph (who is following whom) is also publicly available, the feed may choose to pull in posts from other users based on these signals.

For example:

• Show top liked posts by people you follow
• Show top liked posts by people followed by people you follow
• Show top replied post by people you follow

All posts

The feed may choose to show all posts.

Feature: Visibility Based on Requesting User

The feed may choose to show content (or return an empty feed) based on criteria of the requesting user.

Example: Cool Club (test) by @jaz.bsky.social

Feature: Static feeds, Pinned posts

The feed may choose to show a constant set of posts, either for the whole feed or just at the beginning of the feed.

Designing Feeds

Considerations

Here are some questions to ask and ideas to ponder about as you design a feed.

Refining the purpose

Feeds can be informational, serve a special purpose, and/or become a rallypoint for a community.

Some intention and research will go a long way. Does such a feed already exist? If it does, is it still meaningful to have a separate feed? What kind of posts are you intending to show in your feed?

If it seems like the feed might already exist, consider:

• creating a smaller niche (Detroit Tigers) inside the larger community (Major League Baseball)
• creating a larger umbrella (baseball) which contains the existing communities, and others (college baseball, Minor League Baseball)
• providing a new special purpose: a feed that shows a user's most replied to posts

Understand the maintenance level

Many feeds are built once and rarely updated. Other feeds may require user list maintenance, content curation, and/or troubleshooting.

Ease of use and ease of discovery

Both the name and description have character limits, so every word counts.

The name should be simple and highly searchable.

The description should give folks a good idea of its purpose, how it works or what it does, such as: "Tracks emoji X" or "contact Y to be added to the list."

The feed avatar should be recognizable and well-framed.

For more information (such as a Google form, or a full list of keywords), you may consider adding URLs in the description. Note linking doesn't presently work for feeds in the app, so this is where short domains or link shorteners may shine. Alternatively, you may consider the Instagram method of "check in bio" and link from your bio.

Getting the word out

Here are the ways people may come across feeds:

• going to a profile in-app and to the Feeds tab
• seeing it in the "Discover Feeds" section in-app, which contains the Top 50 feeds by most likes
• searching for keywords in places like goodfeeds
• seeing the feed embedded in posts

You might reply to posts found in your feed to let people know. You may also consider building a separate feed which looks for people interested in the topic and looking for a feed.

Best practices for sharing feeds

Each feed has a URL that looks like https://bsky.app/profile/did:plc:ABC/feed/XYZ

To find the URL, navigate to the feed directly (not in one's pinned tabs), and either:

• copy the URL in the browser
• or on mobile, click on "Share Link" in the dropdown menu. (You may have to add the feed first.)

When sharing the link, be sure to click on "Add link card", so the inline card showing the feed name and like count (i.e. the post embed) shows up.

When encouraging others to share, you may want to remind folks to:

• add the feed: this adds the feed to the user's Feeds section
• click the thumbtack / pin the feed: this brings the feed into the main Home section of the app, so it's more accessible than the Feeds section
• click the heart / like the feed: this helps in any rankings by like count (such as Discover Feeds), and also adds to the list of feed likers