Wallabag.el

#+TITLE: README #+DATE: April 13, 2021 #+SINCE: <replace with next tagged release version> #+STARTUP: inlineimages nofold

[[https://melpa.org/#/wallabag][file:https://melpa.org/packages/wallabag-badge.svg]]

• Table of Contents :TOC_1:noexport:

• [[#description][Description]]
• [[#features][Features]]
• [[#installation-and-configuration][Installation and Configuration]]
• [[#image-caching][Image Caching]]
• [[#retrieve-new-entries-after-m-x-wallabag][Retrieve new entries after =M-x wallabag=]]
• [[#use-org-protocol-to-save-page][Use org-protocol to save page]]
• [[#use-ai-to-generate-summary][Use AI to generate summary]]
• [[#keybindings][Keybindings]]

• Description Emacs [[https://github.com/wallabag/wallabag][Wallabag]] client. #+attr_org: :width 600px [[file:images/homepage.png]]

#+attr_org: :width 600px [[file:images/paw.png]]

• Features

• Request all entries
• Request all tags
• Add tags for one entry
• Delete tag for one entry
• Request format for one entry
• Add entry (Support from eaf browser or elfeed or org-protocol)
• Insert entry with provided html (Support from eaf browser or elfeed or org-protocol)
• Delete entry
• Copy as org/markdown/org-protocol links
• Offline database (Sqlite)
• Full update
• Sidebar supported
• Select with Ivy/Consult
• sync with all clients (mobile, web, browser extension etc)
• Beautify: Support [[https://github.com/chenyanming/shrface][shrface]]
• Real time search and filtering (space separated)
• Annotation: Support [[https://github.com/chenyanming/paw][paw]]
• Cache support: Saved placed/AI Summary Cache
• Org Protocol Support

• Installation and Configuration This project relies on [[https://github.com/tkf/emacs-request][emacs-request]] and [[https://github.com/skeeto/emacsql][emacsql]]. Please install them in advanced.

#+begin_src sh git clone https://github.com/chenyanming/wallabag.el.git ~/.emacs.d/lisp/wallabag/ #+end_src

** Melpa It's available on [[https://melpa.org/][Melpa]] :

#+BEGIN_SRC emacs-lisp M-x package-install wallabag #+END_SRC

** require #+BEGIN_SRC emacs-lisp (add-to-list 'load-path "~/.emacs.d/lisp/wallabag/") (require 'wallabag) (setq wallabag-host "https://xx.xx.xx") ;; wallabag server host name (setq wallabag-username "xx") ;; username (setq wallabag-password "xx") ;; password (setq wallabag-clientid "xx") ;; created with API clients management (setq wallabag-secret "xx") ;; created with API clients management (setq wallabag-search-print-items '("title" "domain" "tag" "reading-time" "date")) ;; control what content should be show in wallabag-search (setq wallabag-search-page-max-rows 32) ;; how many items shown in one page #+END_SRC

** use-package (load-path) #+begin_src emacs-lisp (use-package wallabag :defer t :load-path "~/.emacs.d/lisp/wallabag/" :config (setq wallabag-host "https://xx.xx.xx") ;; wallabag server host name (setq wallabag-username "xx") ;; username (setq wallabag-password "xx") ;; password (setq wallabag-clientid "xx") ;; created with API clients management (setq wallabag-secret "xx") ;; created with API clients management (setq wallabag-search-print-items '("title" "domain" "tag" "reading-time" "date")) ;; control what content should be show in wallabag-search (setq wallabag-search-page-max-rows 32) ;; how many items shown in one page ;; (setq wallabag-db-file "~/OneDrive/Org/wallabag.sqlite") ;; optional, default is saved to ~/.emacs.d/.cache/wallabag.sqlite ) #+end_src

** use-package (Straight) #+begin_src emacs-lisp (use-package wallabag :straight (:host github :repo "chenyanming/wallabag.el" :files (".el" ".alist" "*.css"))) #+end_src

** Doom Emacs (package!) #+begin_src emacs-lisp (package! wallabag :recipe (:host github :repo "chenyanming/wallabag.el" :files (".el" ".alist" "*.css"))) #+end_src ** Store sensitive credentials in ~auth-sources~ It is insecure to store your sensitive credentials such as the wallabag password and client secret in plain text, and especially if you want to be upload it to public servers. You can use Emacs' built-in [[https://www.gnu.org/software/emacs/manual/html_mono/auth.html][auth-sources]] library for GPG-encrypted storage of your secrets.

Create an encrypted =~/.authinfo.gpg= file with the lines: #+begin_src machine wallabag domain "https://example.com" user "xxx" password "xxx" clientid "xxx" client-secret "xxx" #+end_src

Wallabag will get the credentials when needed without saving them in memory.

You can also hardcode ~wallabag-host~, ~wallabag-username~, ~wallabag-password~, ~wallabag-clientid~, ~wallabag-secret~ but it is less secure.

• Image Caching Wallabag will not download the images, but using Emacs [[https://www.gnu.org/software/emacs/manual/html_node/url/Disk-Caching.html][disk caching]] capability. Setting ~url-automatic-caching~ non-nil causes documents to be cached automatically. #+begin_src emacs-lisp (setq url-automatic-caching t) #+end_src

• Retrieve new entries after =M-x wallabag= #+begin_src emacs-lisp (add-hook 'wallabag-after-render-hook 'wallabag-search-update-and-clear-filter) #+end_src

• Use org-protocol to save page Add wallabag org protocol by running: #+begin_src emacs-lisp (wallabag-org-setup-org-protocol) #+end_src

Create a bookmarklet with:

• If [[https://www.piwheels.org/project/emacs-paw/][paw-server]] is running, use [[file:js/wallabag_insert_entry.js]] (send html to paw-server, and save the page to wallabag)
• If [[https://www.piwheels.org/project/emacs-paw/][paw-server]] is not running, use [[file:js/wallabag_add_entry.js]] (only send url to wallabag server)

• Use AI to generate summary #+begin_src emacs-lisp M-x wallabag-summary ;; or press ? #+end_src Wallabag will use gptel to generate the summary overlay into the begining of the article.

#+attr_org: :width 600px [[file:images/summary.gif]]

• Keybindings Start with ~M-x wallabag~. For the first time you connect to server, you need to press ~u~ to synchronize.

** Functions can be used outside wallabag related modes | wallabag | Enter ~wallabag-search~ buffer. | | wallabag-find | Select wallabag entries from a list with ivy. | | wallabag-full-update | Perform a full database update. It can always keep the local database updated. | | wallabag-request-token | Request a new token. | | wallabag-add-entry | Add one entry to wallabag server, with URL and TAGS | | wallabag-insert-entry | Insert an entry to wallabag server with current buffer content (behavior may be changed in the future) | | wallabag-request-new-entries | Request the new entries in the background. | | wallabag-request-and-synchronize-entries | Request and synchronize entries, controlled by ~wallabag-number-of-entries-to-be-synchronized~. |

** wallabag-search-mode

| <RET>                 | wallabag-view                                | View the wallabag entry.                                                   |
| v                     | wallabag-view                                | View the wallabag entry.                                                   |
| V                     | wallabag-browse-url                          | Browse the url of current wallabag entry.                                  |
| o                     | wallabag-original-entry                      | Open the original html rendered wallabag entry.                            |
| s (non-evil), /(evil) | wallabag-search-live-filter                  | Filter the ~*wallabag-search*~ buffer.                                       |
| q                     | wallabag-search-quit                         | Quit ~*wallabag-entry*~ then ~*wallabag-search*~ and ~*wallabag-sidebar*~.       |
| g (non-evil), r(evil) | wallabag-search-refresh-and-clear-filter     | Refresh wallabag and clear the filter keyword.                             |
| G (non-evil), R(evil) | wallabag-search-clear-filter                 | Clear the filter keyword.                                                  |
| u                     | wallabag-search-update-and-clear-filter      | Request new entries, clear the filter keyword, and update *wallabag-search*. |
| U                     | wallabag-search-synchronize-and-clear-filter | Synchronize entries, clear the filter keyword, and update *wallabag-search*. |
| m                     | wallabag-mark-and-forward                    | Mark entry and forward.                                                    |
| <DEL>                 | wallabag-unmark-and-backward                 | Unmark entry and backword.                                                 |
| a                     | wallabag-add-entry                           | Add an entry.                                                              |
| d                     | wallabag-delete-entry                        | Delete an entry.                                                           |
| n(non-evil), j(evil)  | wallabag-next-entry                          | Move to next entry.                                                        |
| p(non-evil), k(evil)  | wallabag-previous-entry                      | Move to previous entry.                                                    |
| w(non-evil), y(evil)  | wallabag-org-link-copy                       | Copy marked entries as org links.                                          |
| t                     | wallabag-add-tags                            | Add tags (seperated by comma) to entry at point.