DOCSEARCHbyAlgolia
Submit Docs

Elfeed Documentation

repository·main·Indexed 23 days ago

https://github.com/emacs-elfeed/elfeed

An extensible web feed reader for Emacs supporting Atom, RSS, and JSON feeds. It features a tag-based search interface, deep customization via hooks and metadata, and requires Emacs 29.1 or later. The documentation covers installation, search buffer navigation, tag-based filtering syntax, automation via elfeed-new-entry-hook, and custom metadata management using elfeed-meta.

Tokens
1.7K
Snippets
4
Records
6
Agent score
33%

What's inside Elfeed

  1. Filter Elfeed entries using Tag Syntax

    main

    The Elfeed search buffer can be filtered using a specific syntax in the search string. Any component not starting with a special symbol is treated as a regular expression matching the entry's title or URL.

    Filter Symbols

    • +tag: Required tag (must be present).
    • -tag: Excluded tag (must not be present).
    • @age: Age or date range restriction.
      • Relative: @2years, @3-days-ago (use dashes instead of spaces).
      • Absolute: @2019-06-24.
      • Range: @2019-06-20--2019-06-24 or @5-days-ago--1-day-ago.
      • Note: Filters with age restrictions are significantly more efficient.
    • !regex: Inverse regular expression (matches entries NOT matching the regex).
    • #number: Limit the total number of entries displayed (e.g., #20).
    • ~~regex: Include only entries where the feed (title/URL) matches the regex.
    • =~regex: Exclude entries where the feed (title/URL) matches the regex.

    Examples

    • @6months +unread: Unread entries from the last six months.
    • linu[xs] @1-year-old: Entries about Linux or Linus from the last year.
    • -unread +youtube #10: 10 most recent read entries tagged youtube.
    • +unread !x?emacs: Unread entries not containing emacs or xemacs in title/link.

  2. Use the Elfeed Search Buffer

    main

    Running elfeed opens the *elfeed-search* buffer. This buffer displays feed items and provides several interactive commands:

    View and Navigation

    • RET: View selected entry in a buffer
    • b: Open selected entries in your browser
    • B: Open selected entries in your secondary browser
    • y: Copy selected entries URL to the clipboard

    Tagging and Marking

    • r: Tag selected entries as read (C-u r tags all)
    • u: Tag selected entries as unread (C-u u tags all)
    • +=: Add a specific tag to selected entries
    • -=: Remove a specific tag from selected entries
    • m: Mark candidate
    • M: Unmark candidate (C-u M unmarks all)
    • t: Set title of selected entry
    • T: Set title of selected feed

    Refreshing and Filtering

    • g: Refresh view of the feed listing
    • G: Fetch feed updates from the servers (or use M-x elfeed-update)
    • s: Update the search filter
    • S: Update the search filter statically
    • c: Clear the search filter
    • @: Add current date to the filter
    • ~~: Only include current feed
    • =~: Exclude current feed

  3. Install and Set Up Elfeed

    main

    Elfeed is an extensible web feed reader for Emacs supporting Atom, RSS, and JSON Feed. It requires Emacs 29.1 or later.

    Installation

    Install via M-x package-install using ELPA or MELPA.

    Prerequisites

    It is strongly recommended to have curl installed and available in your PATH (or configured via elfeed-curl-program-name). Elfeed prefers curl over Emacs' built-in url-retrieve for faster updates and better stability, especially on Windows.

    To disable curl and use the built-in method, set elfeed-use-curl to nil.

    Initial Configuration

    Add your feeds to the elfeed-feeds variable. You can also use an OPML file by running M-x elfeed-load-opml.

    ;; Global binding for the main entry point
(keymap-global-set "C-x w" #'elfeed)

;; Configure your feeds
(setq elfeed-feeds
      '("https://nullprogram.com/feed/"
        "https://planet.emacslife.com/atom.xml"))

  4. Configure per-feed options in elfeed-feeds

    main

    The elfeed-feeds variable can accept a list where each item is a plist of options followed by autotags. Supported special keys include:

    • :no-update: Prevent the feed from updating during elfeed-update.
    • :fetch-link: Automatically fetch the content of the entry link and display it in the elfeed-show buffer.
    • :readable: Enable readable mode in the elfeed-show buffer.
    • :show-entry: Specify an alternative show function (e.g., browse-url).
    • :title: Override the feed title.

    Example configuration:

    (setq elfeed-feeds
      '(("https://planet.emacslife.com/atom.xml" :no-update t :title "Planetemacs" emacs)
        ("https://sachachua.com/blog/category/emacs-news/feed/" :show-entry eww-browse-url emacs)
        ("https://www.debian.org/security/dsa" :fetch-link replace :readable t security)))```

    ```emacs-lisp
(setq elfeed-feeds
      '(("https://planet.emacslife.com/atom.xml" :no-update t :title "Planetemacs" emacs)
        ("https://sachachua.com/blog/category/emacs-news/feed/" :show-entry eww-browse-url emacs)
        ("https://www.debian.org/security/dsa" :fetch-link replace :readable t security)))```

  5. Automate tagging with elfeed-new-entry-hook

    main

    You can use elfeed-new-entry-hook to automatically apply tags to new entries as they are discovered. This is useful for organizing feeds based on URL patterns or titles.

    To apply hooks to existing entries in the database, run M-x elfeed-apply-hooks-now.

    ;; Mark all YouTube entries automatically
(add-hook 'elfeed-new-entry-hook
          (elfeed-make-tagger :feed-url "youtube\\.com"
                              :add '(video youtube)))

;; Tag entries older than 2 weeks as read
(add-hook 'elfeed-new-entry-hook
          (elfeed-make-tagger :before "2 weeks ago"
                              :remove 'unread))

  6. Manage custom metadata with elfeed-meta

    main

    Elfeed allows you to store arbitrary, readable values in a metadata plist for both feeds and entries. These values are automatically persisted in the database. You access and modify them using the polymorphic elfeed-meta function, which is setf-able.

    Important: You must (require 'elfeed) at the top level of your configuration to allow the Elisp byte compiler to expand the setf macro correctly.

    Usage

    (require 'elfeed)

;; Set and get a custom property on an entry
(setf (elfeed-meta entry :rating) 4)
(elfeed-meta entry :rating) ;; => 4

;; Set and get a custom property on a feed
(setf (elfeed-meta feed :title) "My Better Title")

    To avoid collisions with Elfeed's internal properties (like :authors, :title, :link-content), it is recommended to namespace your own keys (e.g., :my-app/rating).

    (require 'elfeed) ;; Necessary for macro expansion of (setf (elfeed-meta ...) ...)

(setf (elfeed-meta entry :rating) 4)
(elfeed-meta entry :rating)
;; => 4

(setf (elfeed-meta feed :title) "My Better Title")