Config File Explained¶

The initial config file generated on the first run of Feed2Fedi is bare-bones and needs to be edited to make Feed2Fedi work for you. Below is a copy of the bare-bones config file.

   {
     "bot_post_visibility": "unlisted",
     "bot_post_media": true,
     "bot_post_image_selector": "img[src]",
     "bot_post_template_file": "bot_post_template.j2",
     "bot_schedule_duration_delay": "PT5H10M",
     "icecream_enable": false,

     "cache_max_age": 30,
     "cache_db_path": "./cache.sqlite",

     "fedi_instance": "botsin.space",
     "fedi_access_token": "<redacted>",

     "feeds": [
       {
         "url": "http://feedparser.org/docs/examples/rss20.xml",
         "prefix": "Example",
         "max_attachments": 1,
         "post_template_file": "example_feed_template.j2",
         "schedule_duration_delay": "PT5H10M",
         "filters":[
          {"check":"", "check_params": "", "action":"", "action_params":""}
         ],
         "max_age": "PT24H",
         "max_posts": 5,
         "tag_mappings": {
           "website_url": "websiteUrl",
           "categories": "tags"
         }
       }
     ]
   }

Variables starting with `bot_`¶

The variables starting with bot_ specify how Feed2Fedi makes posts on your Fediverse server:

bot_post_visibility = This specifies what kind of visibility Feed2Fedi uses for posts it makes. This can be set to public, unlisted, or private. A post visibility of direct is technically also available but does not make sense in the context of Feed2Fedi. By default Feed2Fedi will post statuses with a visibility of public
bot_post_media = This is a boolean and can be set to either True or False. This setting defaults to False
- True - if set to True Feed2Fedi will attempt to upload any media linked in feed items to your fediverse account and add them to posts.
- False - if set to False Feed2Fedi will just post the title and link of the feed item.
bot_post_image_selector = This is css-like selector that determine what images will be attached to post.
bot_post_template_file = Path to a Jinja2 template file (.j2) for posts. The path is resolved relative to the config file's location. If omitted, Feed2Fedi uses a built-in default that posts the title followed by the link.

See the Template Syntax section below for details. - bot_schedule_duration_delay = This specifies if statuses should be scheduled for future posting. It needs to be set to an ISO 8601 time duration which is added to the current date and time when submitting the status to your fediverse server. If this field is missing (or set to "") statuses will be posted immediately. - icecream_enable = This is a development debug switch. It is optional and if not present defaults to False. If this is set to True Feed2Fedi will print out a lot of debugging information.

Variables starting with `cache_`¶

The variables starting with cache_ define some parameters used to attempt to avoid making duplicate posts.

cache_max_age = This value defines how long URLs of feed items posted to your Fediverse account will be cached. Duplicate checks are performed against the cached URLs. This value defaults to 30 days.
cache_db_path = This value defines the URL cache db file. The URL cache is stored in SQLite database at the location specified in this setting. This setting defaults to storing the URL cache in a SQLite database file stored in the current directory in a file called cache.sqlite

Variables starting with `fedi_`¶

The variables starting with fedi_ specifies the Fediverse account to post statuses to. The easiest way to complete this section is by running Feed2Fedi without these values and Feed2Fedi will ask you for them and update the config file as needed.

See Setting-up-Feed2Fedi for more details.

`feeds` section / Specifying RSS / Atom feeds / filters¶

You can filter out words to prevent their appearance in the Fediverse posts. The filter list consists of dictionaries (it can be zero). The structure is the same as in Feeds. Every dictionary contains mandatory keys check and action and optional keys check_params and action_params The check key defines what kind of checking is applied to every post. It can be:

any = is true for every post.
none = is false for every post
regex = is true if "content_html" matches the regular expression(s) defined in check_params
action = defines what action will be applied to the post(s) if "check" is true for them
none = do nothing
drop = the post won't be published
mark_cw = apply a content warning to the post. the cw text is the string in "action_params"
search_replace = "action_params" should be a dictionary with keys "search" and "replace". It will find the text that matches the regular expression defined in "search" and replace it with the text from "replace". It is possible to use "\number" for linking to an element of the line (see https://docs.python.org/3/library/re.html#index-26)

The fields described below are optional and override any values set on a bot level

schedule_duration_delay = This specifies if statuses should be scheduled for future posting. It needs to be set to an ISO 8601 time duration which is added to the current date and time when submitting the status to your fediverse server. If this field is missing (or set to "") the value of bot_schedule_duration_delay comes into effect.
post_template_file = Path to a Jinja2 template file for this feed's posts. Resolved relative to the config file. If omitted, the value of bot_post_template_file (or the built-in default) is used instead.
max_age = This specifies the maximum age of a feed item for it to be posted. This setting is optional. If it is set to a TimeDelta this will make Feed2Fedi check the pubDate of items and only consider posting items that are less than the TimeDelta old. If present this setting must be a TimeDelta and specified in ISO8601 format.
max_posts = This specifies how many feed items to post as statuses. This setting is optional. If it is specified (as an integer) it will cause Feed2Fedi to stop processing items from the particular feed after having posted max_posts number of items successfully.
tag_mappings = This optional setting allows you to extract custom or non-standard tags from RSS/Atom feeds and make them available in post templates. It is a dictionary that maps template variable names to feed tag names. For example, to use a custom websiteUrl tag from a feed as {{ website_url }} in your template:
```
"tag_mappings": {
  "website_url": "websiteUrl"
}
```
Feed2Fedi handles different types of tag values: - Single values are converted to strings - Arrays of strings are joined with commas (e.g., multiple <category> tags become "CAT 1, CAT 2") - Arrays of dictionaries (like standard <category> tags in RSS) have their term values extracted and joined

Note: Feed tag names are case-insensitive in the mapping (feedparser lowercases all tag names).

For detailed information and examples, see Using Custom Tags.

Examples:

   {"check": "any", "action": "search_replace", "action_params": {"search": "apple", "replace": "orange"}}

string "apple" will be replaced with "orange" in all posts

   {"check": "any", "action": "search_replace", "action_params": {"search": "(@[a-z_-]+) ", "replace": "\1@twitter.com"}}

"@some_name" will be replaced with "some_name@twitter.com" in all posts.

   {"check": "regex", "check_params": ".puppy[- ]?kick.", "action": "mark_cw", "action_params": "Worst crime ever!"}

The content warning "Worst crime ever" will be added to all posts matching the puppy[- ]?kick. regular expression

   {"check": "regex", "check_params": ".puppy[- ]?kick.", "action": "drop"}

Posts matching the regular expression .puppy[- ]?kick. won't be published.

To make Feed2Fedi post items from RSS / Atom feed(s) need to change the feeds section in the config file.

Each individual feed is comprised of a url and optionally a prefix, max_attachments, tag_mappings, and other settings. The url is the link to the actually RSS / Atom feed. If provided, the prefix variable is a string that will be prefixed with each item posted from the feed. This variable defaults to an empty string if not provided. If provided, the max_attachments variable defines the maximum number of images / videos that will be uploaded with each feed item. This can be any positive integer number, including 0, or the string max. The value max will result in Feed2Fedi uploading up to the maximum number of images supported by your fediverse instance. This variable defaults to max If provided, the tag_mappings variable allows you to extract custom tags from the feed and make them available in post templates. See the description above for details on how to use this feature.

Template Syntax¶

Feed2Fedi uses Jinja2 for post templates. Templates are stored in external .j2 files and referenced from the config via bot_post_template_file or post_template_file.

Available variables¶

Variable	Description
`{{ title }}`	Article title
`{{ link }}`	Article URL
`{{ author }}`	Author name
`{{ published }}`	Publication date
`{{ updated }}`	Last updated date
`{{ content_html }}`	HTML content
`{{ content_markdown }}`	Markdown content
`{{ content_plaintext }}`	Plain text content

Custom variables defined via tag_mappings are also available under the name you give them.

Example templates¶

Minimal template (bot_post_template.j2):

{{ title }}

{{ link }}

With optional author (bot_post_template.j2):

{{ title }}{% if author %} by {{ author }}{% endif %}

{{ link }}

With fallback — shows description if present, falls back to title (resolves issue #87):

{{ description | default(title, true) }}

{{ link }}

Truncated title:

{{ title | truncate(100) }}

{{ link }}

Conditional prefix/suffix — equivalent of the old {[ by ]author[.]} syntax:

{% if author and author.strip() %} by {{ author }}.{% endif %}

Migration from the old template syntax¶

If you used the old bot_post_template / post_template inline string fields, run the migration tool:

feed2fedi-migrate-templates --config-file config.json

This performs a dry run — showing you what it would write. To apply the changes:

feed2fedi-migrate-templates --config-file config.json --apply

The tool converts the old syntax to Jinja2 and writes .j2 files alongside your config.

Old syntax	Jinja2 equivalent
`{title}`	`{{ title }}`
`{[Title: ]title}`	`{% if title and title.strip() %}Title: {{ title }}{% endif %}`
`{author[.]}`	`{% if author and author.strip() %}{{ author }}.{% endif %}`
`{[ by ]author[.]}`	`{% if author and author.strip() %} by {{ author }}.{% endif %}`
`{description\\|title}` (fallback)	`{{ description \\| default(title, true) }}`

Config File Explained¶

Variables starting with bot_¶

Variables starting with cache_¶

Variables starting with fedi_¶

feeds section / Specifying RSS / Atom feeds / filters¶