A shortcut is a quick way to get one or more tasks done with your apps. The Apple Shortcuts app lets you create your own shortcuts with multiple steps.

Yomu includes shortcuts to list or open books and annotations and to export them in text, markdown or json format or save the original file. All shortcuts are available directly in the Apple Shortcuts app and can be freely combined with other actions. The provided shortcuts require at least iOS 17.4+ but some actions are only supported for iOS 18 or later.

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
   • Connect Current Book output to Export Book input
   • Choose a format (text, markdown, json)
3. Add Save File shortcut from the Files app

Export all books (example)

1. Add Find Books shortcut
   • Optional: Add Filter (tag, folder, …)
2. Add Repeat with Each action for all books
3. Add Export Book shortcut inside the loop
   • Connect Repeat Item to Export Book input
4. Use the Files app Save File action to save the export
   • Disable Ask Where to Save and select a folder instead
   • Enable Overwrite If File Exists to have only one copy

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
   • Add Filter (type, folder …)
2. Add Repeat with Each action for all books
3. Add Save Book shortcut inside the loop
   • Connect Repeat Item to Save Book input
4. Use the Files app Save File action to save the export
   • Disable Ask Where to Save and select a folder instead
   • Enable Overwrite If File Exists to have only one copy

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
   • Select the book folder as value: Repeat Item -> Folder
2. Define a custom Subpath for the Save File action using the folder name and book title
   • Subpath: Folder->Name/RepeatItem->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.

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
   • Optional: Add Filter (date, title, tag, …)
2. Add Repeat with Each action for all annotations
3. Add Dictionary and set properties from Repeat Item inside the loop
4. 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.

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
   • Optional: Sort by created or modified
2. Optional: Add Choose from List shortcut
3. Add Readwise Service shortcut
   • Connect list output to upload input
   • Enter your Readwise access token

Upload current highlights (example)

1. Add Current Annotations shortcut
2. Add Readwise Service shortcut
   • Enter your Readwise access token

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

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
   • Sort by created or modified
   • Order by latest
   • Limit to 30
2. Add Choose from List action to select some or all annotations
3. Add a Repeat with Each action for the Chosen Items afterwards
4. For each item, create a Dictionary with the highlight attributes
5. Create new Dictionary action to save the export output in the required format
6. Use a Get Contents of URL action and configure it to upload the highlights:
   • POST request to Service API endpoint
   • Request body type File set to the Text contents
   • Headers for json content type and authorization token

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:

– Readwise
https://readwise.io/api_deets

– Raindrop.io
https://developer.raindrop.io/v1/highlights

For other questions or more details about Shortcuts, please refer to Apple’s official documentation and support.

Shortcuts User Guide:
https://support.apple.com/en-us/guide/shortcuts