elfeed-summary/README.org

elfeed-summary

• Installation
• Usage
• Configuration
  • Tree configuration
  • Example
  • Faces
  • Other options

The package provides a tree-based feed summary interface for elfeed. The tree can include individual feeds, searches, and groups. It mainly serves as an easier "jumping point" for elfeed, so searching a subset of the elfeed database is one action away.

Inspired by newsboat.

Installation

As the package isn’t yet available anywhere but in this repository, you can clone the repository, add it to the load-path and require the package. My preferred way is use-package with straight:

(use-package elfeed-summary
  :straight (:host github :repo "SqrtMinusOne/elfeed-summary"))

Of course, you have to have elfeed configured.

Usage

Running M-x elfeed-summary opens up the summary buffer, as shown on the screenshot.

The tree consists of:

• feeds;
• searches;
• groups, that can include other groups, feeds, and searches.

Available keybindings in the summary mode:

Keybinding	Description
RET	Open thing under the cursor (a feed, search, or a group)
M-RET	Open thing under the cursor, but include unread items
q	Quit the summary
r	Refresh the summary buffer
R	Run update for elfeed feeds
u	Toggle showing only unread entries
U	Mark everything in the entry under the cursor as read

The standard keybindings from magit-section are also available, for instance TAB to toggle the visibility of the current group. evil-mode is also supported.

Configuration

Tree configuration

The structure of the tree is determined by the elfeed-summary-settings variable.

This is a list of these possible items:

• Group (group . <group-params>) Groups are used to group elements under collapsible sections.
• Query (query . <query-params>) Query extracts a subset of elfeed feeds based on the given criteria. Each found feed will be represented as a line.
• Search (search . <search-params>) Elfeed search, as defined by elfeed-search-set-filter.
• a few special forms

<group-params> is an alist with the following keys:

• :title (mandatory)
• :elements (mandatory) - elements of the group. The structure is the same as in the root definition.
• :face - group face. The default face is elfeed-summary-group-face.
• :hide - if non-nil, the group is collapsed by default.

<query-params> can be:

• A symbol of a tag. A feed will be matched if it has that tag.
• :all. Will match anything.
• (title . "string") or (title . <form>) Match feed title with string-match-p. <form> makes sense if you want to pass something like rx.
• (author . "string") or (author . <form>)
• (url . "string") or (url . <form>)
• (and <q-1> <q-2> ... <q-n>) Match if all the conditions 1, 2, …, n match.
• (or <q-1> <q-2> ... <q-n>) or (<q-1> <q-2> ... <q-n>) Match if any of the conditions 1, 2, …, n match.
• (not <query>)

Feed tags for the query are determined by the elfeed-feeds variable.

Query examples:

• (emacs lisp) Return all feeds that have either "emacs" or "lisp" tags.
• (and emacs lisp) Return all feeds that have both "emacs" and "lisp" tags.
• (and (title . "Emacs") (not planets)) Return all feeds that have "Emacs" in their title and don't have the "planets" tag.

<search-params> is an alist with the following keys:

• :filter (mandatory) filter string, as defined by elfeed-search-set-filter
• :title (mandatory) title.
• :tags - list of tags to get the face of the entry.

Available special forms:

• :misc - print out feeds, not found by any query above.

Also keep in mind that '(key . ((values))) is the same as '(key (values)). This helps to shorten the form in many cases.

Also, this variable is not validated by any means, so wrong values can produce somewhat cryptic errors. Sorry about that.

Example

Here is an excerpt from my configuration that was used to produce this screenshot:

(setq elfeed-summary-settings
      '((group (:title . "GitHub")
               (:elements
                (query . (url . "SqrtMinusOne.private.atom"))
                (group . ((:title . "Guix packages")
                          (:elements
                           (query . (and github guix_packages)))
                          (:hide t)
                          (:face magit-section-secondary-heading)))))
        (group (:title . "Blogs [Software]")
               (:elements
                (query . software_blogs)))
        (group (:title . "Blogs [People]")
               (:elements
                (query . (and blogs people (not emacs)))
                (group (:title . "Emacs")
                       (:face magit-section-secondary-heading)
                       (:elements
                        (query . (and blogs people emacs))))))
        (group (:title . "Podcasts")
               (:elements
                (query . podcasts)))
        (group (:title . "Videos")
               (:elements
                (group
                 (:title . "Music")
                 (:face magit-section-secondary-heading)
                 (:elements
                  (query . (and videos music))))
                (group
                 (:title . "Tech")
                 (:face magit-section-secondary-heading)
                 (:elements
                  (query . (and videos tech))))
                (group
                 (:title . "History")
                 (:face magit-section-secondary-heading)
                 (:elements
                  (query . (and videos history))))
                ;; ...
                ))
        ;; ...
        (group (:title . "Miscellaneous")
               (:elements
                (group
                 (:title . "Searches")
                 (:face magit-section-secondary-heading)
                 (:elements
                  (search
                   (:filter . "@6-months-ago sqrtminusone")
                   (:title . "About me"))
                  (search
                   (:filter . "+later")
                   (:title . "Check later"))))
                (group
                 (:title . "Ungrouped")
                 (:face magit-section-secondary-heading)
                 (:elements :misc))))))

Faces

As said above, individual group faces can be set with the :face attribute.

Faces for feeds, however, by default reuse the existing elfeed mechanism. The tags for feeds are taken from the elfeed-feeds variable; if a feed has at least one unread entry, the unread tag is added to the list.

This can be overridden by setting the elfeed-summary-feed-face-fn variable.

Searches do mostly the same, but tags for the search are taken from the :tags attribute. This also can be overridden with elfeed-summary-search-face-fn variable.

Other options

Also take a look at M-x customize-group elfeed-summary for the rest of available options.