README

Table of Contents

• Description
• Features
• Installation and Configuration
• Image Caching
• Retrieve new entries after =M-x wallabag=
• Keybindings
• Change logs

Description

Emacs Wallabag client.

Features

• [x] Request all entries
• [x] Request all tags
• [x] Add tags for one entry
• [x] Delete tag for one entry
• [x] Request format for one entry
• [x] Add one entry
• [x] Add one entry with current buffer content (Only Emacs has this feature!)
• [x] Delete one entry
• [x] Copy as org links (Only Emacs has this feature!)
• [x] Offline database (Sqlite)
• [x] Full update
• [x] Real time search and filter
• [x] Sidebar supported
• [x] Select with Ivy
• [x] sync with all clients (mobile, web, browser extention etc)
• [x] Beautify: Support shrface
• [x] Advanced search and filtering (space separated)
• [x] Annotation: Support paw
• [ ] Exporting.
• [ ] Editing.
• [ ] Batch Deletion.
• [ ] Batch Tagging.
• [ ] Sorting.

Installation and Configuration

This project relies on emacs-request and emacsql. Please install them in advanced.

git clone https://github.com/chenyanming/wallabag.el.git ~/.emacs.d/lisp/wallabag/

require

(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

use-package (load-path)

(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-db-file "~/OneDrive/Org/wallabag.sqlite") ;; optional, default is saved to ~/.emacs.d/.cache/wallabag.sqlite
  ;; (run-with-timer 0 3540 'wallabag-request-token) ;; optional, auto refresh token, token should refresh every hour
  )

use-package (Straight)

(use-package wallabag
  :straight (:host github :repo "chenyanming/wallabag.el" :files ("*.el" "*.alist" "*.css")))

Doom Emacs (package!)

(package! wallabag :recipe (:host github :repo "chenyanming/wallabag.el" :files ("*.el" "*.alist" "*.css")))

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 auth-sources library for GPG-encrypted storage of your secrets.

Create an encrypted ~/.authinfo.gpg file with the lines:

machine <wallabag-host> login <username> password <password>
machine <wallabag-client> login <client-id> password <client-secret>

Then, we can use that when setting the wallabag password and secret variables in your config above.

(setq wallabag-password (auth-source-pick-first-password :host "<wallabag-host>")
      wallabag-secret (auth-source-pick-first-password :host "<wallabag-client>"))

Image Caching

Wallabag will not download the images, but using Emacs disk caching capability. Setting url-automatic-caching non-nil causes documents to be cached automatically.

(setq url-automatic-caching t)

Retrieve new entries after M-x wallabag

(add-hook 'wallabag-after-render-hook 'wallabag-search-update-and-clear-filter)

Keybindings

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

PS:

1. The synchronization algorithm is still on development, if you want to keep local database always updated, please use wallabag-full-update.

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.
T	wallabag-remove-tag	Remove one tag from list.
‘	wallabag-toggle-sidebar	Toggle sidebar.
x	wallabag-update-entry-archive	Toggle archive (Read/Unread).
f	wallabag-update-entry-starred	Toggle star (favorites).
i	wallabag-update-entry-title	Update title.
I	wallabag-update-entry-origin_url	Update origin url (from where you found it).

wallabag-entry-mode

r	wallabag-view	Refresh wallabag entry.
M-x	wallabag-browse-url	Browse the url of current wallabag entry.
o	wallabag-original-entry	Open the original html rendered wallabag entry.
q	wallabag-entry-quit	Quit *wallabag-entry*.
mouse-1	wallabag-mouse-1	Browse the url.
ret	wallabag-ret	Browse the url.

wallabag-sidebar-mode

‘	wallabag-toggle-sidebar	Toggle sidebar.
<RET>	wallabag-sidebar-find-tag	Filter by tag at point.
g (non-evil), r(evil)	wallabag-search-clear-filter	Clear the filter keyword.
G (non-evil), R(evil)	wallabag-search-clear-filter	Clear the filter keyword.
n	wallabag-sidebar-find-next-tag	Filter by next tag.
p	wallabag-sidebar-find-previous-tag	Filter by previous tag.
q	wallabag-sidebar-quit	Quit sidebar.

Change logs

2021-04-13

Version 1.1.0:

• Add wallabag-request-new-entries. It only retrieves and update the new entries.
• Add wallabag-search-synchronize-and-clear-filter, and bind to U.
• Rename wallabag-request-entries to wallabag-request-and-synchronize-entries.
• Rename wallabag-number-of-entries-to-be-retrieved to wallabag-number-of-entries-to-be-synchronized.

2021-04-13

Version 1.0.0: