elfeed-summary/README.org

#+TITLE: elfeed-summary

The package provides a tree-based feed summary interface for [[https://github.com/skeeto/elfeed][elfeed]]. The tree can include individual feeds, [[https://github.com/skeeto/elfeed#filter-syntax][searches]], and groups. It mainly serves as an easier "jumping point" for elfeed, so to make querying a subset of the elfeed database is one action away.

Inspired by [[https://github.com/newsboat/newsboat][newsboat]].

[[./img/screenshot.png]]

* 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=:
#+begin_src emacs-lisp
(use-package elfeed-summary
  :straight (:host github :repo "SqrtMinusOne/elfeed-summary"))
#+end_src

Of course, you have to have [[https://github.com/skeeto/elfeed][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 | Command                             | Description                                                                                                                     |
|------------+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------|
| =RET=      | =elfeed-summary--action=            | Open thing under the cursor (a feed, search, or a group). If there is at least one unread item, it will show only unread items. |
| =M-RET=    | =elfeed-summary--action-show-read=  | Open thing under the cursor, but always include read items                                                                      |
| =q=        | ...                                 | Quit the summary buffer                                                                                                         |
| =r=        | =elfeed-summary--refresh=           | Refresh the summary buffer                                                                                                      |
| =R=        | =elfeed-summary-update=             | Run update for elfeed feeds                                                                                                     |
| =u=        | =elfeed-summary-toggle-only-unread= | Toggle showing only unread entries                                                                                              |
| =U=        | =elfeed-summary--action-mark-read=  | Mark everything in the entry under the cursor as read                                                                           |

The standard keybindings from [[https://magit.vc/manual/magit.html#Sections][magit-section]] are also available, for instance =TAB= toggles the visibility of the current group. [[https://github.com/emacs-evil/evil][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:
#+begin_src emacs-lisp
(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)))))
        (group (:title . "Blogs [Software]")
               (:elements
                (query . software_blogs)))
        (group (:title . "Blogs [People]")
               (:elements
                (query . (and blogs people (not emacs)))
                (group (:title . "Emacs")
                       (:elements
                        (query . (and blogs people emacs))))))
        (group (:title . "Podcasts")
               (:elements
                (query . podcasts)))
        (group (:title . "Videos")
               (:elements
                (group
                 (:title . "Music")
                 (:elements
                  (query . (and videos music))))
                (group
                 (:title . "Tech")
                 (:elements
                  (query . (and videos tech))))
                (group
                 (:title . "History")
                 (:elements
                  (query . (and videos history))))
                ;; ...
                ))
        ;; ...
        (group (:title . "Miscellaneous")
               (:elements
                (group
                 (:title . "Searches")
                 (:elements
                  (search
                   (:filter . "@6-months-ago sqrtminusone")
                   (:title . "About me"))
                  (search
                   (:filter . "+later")
                   (:title . "Check later"))))
                (group
                 (:title . "Ungrouped")
                 (:elements :misc))))))
#+end_src

** Faces
Faces for groups by default use the =elfeed-summary-group-faces= variable, which serves as a list of faces for each level of the tree. Individual group faces can be overridden with the =:face= attribute.

Faces for feeds by default reuse [[https://github.com/skeeto/elfeed#custom-tag-faces][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 are mostly the same as feeds, 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.