org-readwise is an Emacs package that integrates the Readwise.io highlight syncing service with Org-mode. It allows you to sync your Readwise highlights and notes into your Org files.

• Sync highlights and notes from Readwise.io.
• Output highlights and notes to an Org buffer or a specified file.
• Supports customizable debug levels for detailed logging.
• Handles pagination and updates efficiently.

To install `org-readwise`, you can either use a package manager like `straight.el` or `quelpa`, or clone the repository manually.

Ensure you have `straight.el` installed and then add the following to your Emacs configuration:

;; Bootstrap straight.el
(let ((bootstrap-file (concat user-emacs-directory "straight/repos/straight.el/bootstrap.el"))
      (bootstrap-version 5))
  (unless (file-exists-p bootstrap-file)
    (with-current-buffer
        (url-retrieve-synchronously
         "https://raw.githubusercontent.com/raxod502/straight.el/develop/install.el"
         'silent 'inhibit-cookies)
      (goto-char (point-max))
      (eval-print-last-sexp)))
  (load bootstrap-file nil 'nomessage))

(straight-use-package 'use-package)

;; Install org-readwise from GitHub
(use-package org-readwise
  :straight (org-readwise :type git :host github :repo "CountGreven/org-readwise")
  :config
  ;; Ensure auth-source is configured to find your Readwise token
  (setq auth-sources '("~/.authinfo.gpg"))
  
  ;; Set the output location for your highlights (buffer or file)
  (setq org-readwise-output-location "~/org/readwise-highlights.org")
  
  ;; Optionally set the debug level (0 = no debug, 1 = basic debug, 2 = detailed debug)
  (setq org-readwise-debug-level 1))

Ensure you have `quelpa` installed and then add the following to your Emacs configuration:

;; Install quelpa
(unless (package-installed-p 'quelpa)
  (package-refresh-contents)
  (package-install 'quelpa))

;; Install org-readwise from GitHub using quelpa
(use-package org-readwise
  :quelpa (org-readwise :fetcher github :repo "CountGreven/org-readwise")
  :config
  ;; Ensure auth-source is configured to find your Readwise token
  (setq auth-sources '("~/.authinfo.gpg"))
  
  ;; Set the output location for your highlights (buffer or file)
  (setq org-readwise-output-location "~/org/readwise-highlights.org")
  
  ;; Optionally set the debug level (0 = no debug, 1 = basic debug, 2 = detailed debug)
  (setq org-readwise-debug-level 1))

To install manually, clone the repository and load the package in your Emacs configuration:

git clone https://github.com/CountGreven/org-readwise.git ~/.emacs.d/org-readwise/

Then add the following to your Emacs configuration:

(add-to-list 'load-path "~/.emacs.d/org-readwise/")
(require 'org-readwise)

;; Ensure auth-source is configured to find your Readwise token
(setq auth-sources '("~/.authinfo.gpg"))

;; Set the output location for your highlights (buffer or file)
(setq org-readwise-output-location "~/org/readwise-highlights.org")

;; Optionally set the debug level (0 = no debug, 1 = basic debug, 2 = detailed debug)
(setq org-readwise-debug-level 1)

To use `org-readwise`, you need to configure it with your Readwise API token. The token should be stored in one of the files defined in `auth-sources`.

Example configuration:

;; Ensure auth-source is configured to find your Readwise token
(setq auth-sources '("~/.authinfo.gpg"))

;; Set the output location for your highlights (buffer or file)
(setq org-readwise-output-location "~/org/readwise-highlights.org")

;; Optionally set the debug level (0 = no debug, 1 = basic debug, 2 = detailed debug)
(setq org-readwise-debug-level 1)

;; Sync highlights
(org-readwise-sync)

org-readwise requires an access token for Readwise, which should be stored in your `authinfo.pgp` file.

Example `authinfo.pgp` entry:

machine readwise.io login <your-email> password <your-readwise-token>

Here’s the syntax breakdown:

• `machine readwise.io`: The host for Readwise API.
• `login <your-email>`: Your Readwise login email.
• `password <your-readwise-token>`: Your Readwise access token.

You can customize the behavior of `org-readwise` through the following variables:

• `org-readwise-output-location`:
  • Specify where to output the Readwise highlights: ‘buffer or a file path.
  • If set to ‘buffer, an ephemeral buffer called Readwise-Highlights will be created where the highlights will be synced. This buffer will be temporary and is useful for quick reviews or temporary storage.
  • Example: `(setq org-readwise-output-location ‘buffer)` or `(setq org-readwise-output-location “~/org/readwise-highlights.org”)`
• `org-readwise-debug-level`:
  • Specify the debug level for `org-readwise`.
  • 0 = no debug output, 1 = basic debug output, 2 = detailed debug output.
  • Example: `(setq org-readwise-debug-level 1)`

org-readwise uses a timestamp file to keep track of the last successful sync. This ensures that only highlights added or updated since the last sync are fetched, reducing the amount of data transferred and processed. The timestamp file location is customizable through `org-readwise-last-sync-time-file`, which defaults to `~/.emacs.d/org-readwise-last-sync`.

You can customize the location of the timestamp file:

;; Set the location of the last sync time file
(setq org-readwise-last-sync-time-file "~/.emacs.d/org-readwise-last-sync")

To sync your Readwise highlights, run:

M-x org-readwise-sync

This will fetch your highlights and insert them into the specified output location. If using the buffer output, highlights will be displayed in a temporary buffer called `*Readwise Highlights*`.

To sync all highlights regardless of the last sync time, call the function with a universal argument:

C-u M-x org-readwise-sync

• No real-time sync: Manual trigger required for syncing.
• Single user setup: Designed for single user configurations.
• Performance: Syncing a large number of highlights can be slow.
• Customization needed: Advanced configurations might require code adjustments.
• Overwrites buffer: Currently, the program will overwrite the buffer of highlights with the newly synced highlights.
• No awareness of moved highlights: The program is not aware if the user moves a highlight, potentially causing duplication or loss of highlights.

Contributions are welcome! Feel free to open issues or submit pull requests on the GitHub repository.

This package is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.