David Blue

This is a private note that has been shared.

Yomu Annotations Update/Export Shortcut/Automation

Updated 01212025-073804

Yomu Shortcuts Reference

Shortcuts
Find Books
Find Annotations
Launch App
Continue Reading
Current Book
Open Book
Save Book
Export Book
Current Annotations
Open Annotation
Export Annotation
Readwise Service

How can I use Shortcuts to export books?

Individual books can be exported in text, markdown or json format with the Export Book shortcut. It can be used together with the Current Book or Find Books action, which lets you get a filtered list of books to automate saving metadata and annotations of all your books.

Export book (example)

  1. Add Export Book shortcut
  2. Choose a format (text, markdown, json)
  3. Choose book or run to select from recents

Export current book (example)

  1. Add Current Book shortcut
  2. Add Export Book shortcut
  1. Add Save File shortcut from the Files app

Export all books (example)

  1. Add Find Books shortcut
  1. Add Repeat with Each action for all books
  2. Add Export Book shortcut inside the loop
  1. Use the Files app Save File action to save the export

How can I use Shortcuts to save books?

You can save all original book files to create a backup of your library on iCloud Drive with the Save Book shortcut.

Save all books (example)

  1. Add Find Books shortcut
  1. Add Repeat with Each action for all books
  2. Add Save Book shortcut inside the loop
  1. Use the Files app Save File action to save the export

Itā€™s also possible to re-create the folder structure but itā€™s a bit difficult to get this to work with the Shortcuts app. You will need to modify the save books shortcut to get the folder name and file name to define a custom subpath for the Save File action.

Save books folder (example)

  1. Use a Set Variable action inside the loop
  1. Define a custom Subpath for the Save File action using the folder name and book title

Note: This shortcut can fail with ā€œCouldnā€™t communicate with helper applicationā€, this is an error message from the Apple Shortcuts app. Most likely the problem is that it runs out of memory with large files. As a workaround, try to run the shortcut from your Mac or from a device with more memory. As an alternative, you can also set a filter in the Find Books action to only save epub formats and exclude large file types such as pdf or comics.

How can I use Shortcuts to export annotations?

You can export individual annotations in text, markdown or json format with the Export Annotation shortcut.

Export annotation (example)

  1. Add Export Annotation shortcut
  2. Choose a format (text, markdown, json)
  3. Choose annotation or run to select from latest

Another option is to create your own annotation export. You can use the Find Annotations shortcut to get a filtered list of all annotations or the Current Annotations action to save all annotations of your current book.

Export all annotations (example)

  1. Add Find Annotation shortcut
  1. Add Repeat with Each action for all annotations
  2. Add Dictionary and set properties from Repeat Item inside the loop
  3. Create new Dictionary action to save the export output in the required format

This example iterates over all annotations and creates a new dictionary for each entry with specific annotation properties. The result output can be used as a json payload to upload highlights to external services.

How do I use Shortcuts to upload highlights to Readwise?

Yomu includes a convenience shortcut to upload highlights to the Readwise service. It can be used to upload all or selected highlights with the Find Annotations action or to just upload the Current Annotations of a book.

Upload highlights (example)

  1. Add Find Annotations shortcut
  1. Optional: Add Choose from List shortcut
  2. Add Readwise Service shortcut

Upload current highlights (example)

  1. Add Current Annotations shortcut
  2. Add Readwise Service shortcut

You can obtain your personal Readwise access token from their service https://readwise.io/access_token

How do I use Shortcuts to upload highlights to other services?

With Shortcuts, annotation export and upload to external services can be automated. Here is an example for Readwise, but the same concepts can be used for other service APIs as well.

Service upload (example)

  1. Add Find Annotation shortcut with optional filters
  1. Add Choose from List action to select some or all annotations
  2. Add a Repeat with Each action for the Chosen Items afterwards
  3. For each item, create a Dictionary with the highlight attributes
  4. Create new Dictionary action to save the export output in the required format
  5. Use a Get Contents of URL action and configure it to upload the highlights:

In summary, the shortcut transforms your annotations to the required json structure and uploads it to the Readwise highlights API endpoint. The text conversion is a workaround, because the Get Contents action somehow does not accept dictionaries for json body type inputs. This solution is based on the custom json payload approach published in Alex W.ā€™s blog.

This approach will only work with more than one annotation. The problem is that the Shortcuts app somehow converts list output to an object instead of an array if there is only one item contained. You would need to modify the shortcut to handle zero/one or multiple annotations.

How you structure or upload highlights depends on the service. Refer to their documentation to learn more: