org-books

Reading list management using org-mode. Originally forked from https://github.com/lepisma/org-books by @lepisma (Abhinav Tushar), although by now there is little code in common between the two versions.

This is my fork with some additional functionality I wanted for myself, All credit for the idea and original implementation goes to @lepisma. See the original version for a tutorial.

Differences from the original version

• NEW: added support for TheStoryGraph (including series URLs!).
• NO HELM. The helm dependency has been dropped in favour of consult.
• More details from Goodreads.
  • Automate genre tagging by customizing the org-books-genre-tag-associations variable! (More info below.)
• Support for OpenLibrary and LibraryThing.
  • Can add whole series from TheStoryGraph and LibraryThing (just use the series URL)!
  • When scraping from LibraryThing, optionally fetch additional data from Amazon automatically (see the org-books-librarything-get-amazon-details variable). Try with a series link for extra oomph!
• Automated property and state assignment with in-built functions.
• Re-read tracking.
• Jump to reading: quickly find books that you are reading right now.
• New reading state: DNF! For books you cannot even. (Supports re-read functionality!)
• Quality of life improvements:
  • If org-books-add-url fails, it will ask to retry.
  • Helm call for location of new book has been simplified, and should run faster.

TheStoryGraph tags

One of TheStoryGraph’s features is its unique and intuitive tag system. Org-books will fetch those tags for you and add them straight to the book heading!

Goodreads details

The function org-books-get-details-goodreads now fetches not just the author and book name, but also the publication year, page count, and Goodreads rating. Some books have the publication year for a newer edition, and the original publication year in parentheses: in these cases the function fetches the original publication year. The function also adds a timestamp of the date the book was added to the collection.

Automatic genre tagging

The variable org-books-genre-tag-associations is a hash table that lets you customize which genre tags (Goodreads only so far) are assigned upon adding a book to your org-books file.

Say you read a lot of urban fantasy, and you’d like to have tags on all your urban fantasy books, but you don’t want to assign them every time by hand. This is where automatic genre tagging comes in handy: if a book is tagged as “Urban Fantasy” on Goodreads, org-books will automatically assign it a tag of your choice.

You can enable this functionality by adding something like this to your config:

(map-put! org-books-genre-tag-associations "Urban Fantasy" "urban")

where the key is the exact genre tag as it appears on Goodreads, and the value is what you want it to be tagged as in org-books.

Multiple keys can be assigned to the same value. Deduplication of tags is handled automatically during assignment.

State tracking and re-reads

I rehauled the org-books-rate-book function and added a counterpart for beginning a book: org-books-start-reading. These functions now do two things:

• set the TODO state (‘READING’ or ‘READ’),
• add a timestamp to the book’s properties.

Moreover, the functions support re-reads. On every new read, the new starting date, completion date, and rating are all recorded separately.

Core functions for everyday use

Consider giving keybindings to the following functions:

• org-books-add-url: to add new books to the collection.
  • Alternatively org-books-cliplink to add a link from the clipboard.
• org-books-start-reading: when beginning to read a new book (to change its state to READING and timestamp the starting date).
• org-books-rate-book: when you finish a book (to give it a rating from 1 to 5, change its state to READ, and timestamp the finished date).
  • org-books-dnf: if for whatever reason you cannot keep reading, abandon ship and mark the book as unfinished.
• org-books-jump-to-reading: quickly find a book with a READING status. You can use this anywhere, not just in the org-books file.

A good way to use this package is by creating a derived org-books-mode, so that your org-books keybindings are safely contained within it, and do not interfere with your other org-mode workflows.