Unread’s Shortcuts feature allows paying subscribers to run shortcuts on articles and links. The shortcuts are defined in the Shortcuts app.
On iPhone and iPad, a shortcut can be run from the swipe left menu of an article, the context menu of an article in an article list, or the context menu of a link in an article. On a device with a hardware keyboard, you can also define a hardware keyboard shortcut for each.
On Mac, a shortcut can be run from the Article menu, from the context menu of an article in an article list, or from the context menu of a link in an article. A keyboard shortcut can be set for each. An optional toolbar menu can be added to viewer windows and standalone article windows as well.
Writing a Shortcut
The Shortcut Input when run from Unread is a JSON string like this one:
{
"type": "article",
"url": "https://www.goldenhillsoftware.com/2024/11/unread-43-adds-new-article-actions-customizable-keyboard-shortcuts-for-article-actions-and-ability-to-invoke-shortcuts-on-articles/",
"article_url": "https://www.goldenhillsoftware.com/2024/11/unread-43-adds-new-article-actions-customizable-keyboard-shortcuts-for-article-actions-and-ability-to-invoke-shortcuts-on-articles/",
"title": "Unread 4.3 Adds New Article Actions, Customizable Keyboard Shortcuts for Article Actions, and Ability to Invoke Shortcuts on Articles",
"feed_name": "Golden Hill Software",
"summary": "Unread 4.3 is available. This update adds these improvements and more: Article actions for Anybox, Flyleaf, Matter, and wallabag.",
"author": "John Brayton",
"date": "2024-11-19T15:00:49Z",
"selected_text": "Unread 4.3 is available. This update adds these improvements and more:",
"selected_html": "<p>Unread 4.3 is available. This update adds these improvements and more:</p>"
}
Each shortcut to be run from Unread should start with a Get Dictionary from Input action, with Shortcut Input as the input to that action. That will convert the string such as the one above to a dictionary. Subsequent actions will operate on the contents of that dictionary.
Each shortcut should end with a Stop and Output action. Leave the action input as the default, and leave the If there's nowhere to output setting as Do Nothing. This prevents Shortcuts from asking permission to send output back to Unread.
Shortcut Input Dictionary
When running a shortcut, Unread sends these key-value pairs:
type: This will be “article” when the shortcut is run on an article, and “link” when the shortcut is run on a link inside an article. It will always be present.
url: This is the URL of the article or link. It will always be present.
article_url: This is the URL of the article. It will always be present for articles, and will never be present for links. Under most circumstances the value will be equal to the url value for an article. (Details below.)
linked_article_url: For link articles, this will be the URL of the article linked to by the publisher of the feed. It will be present for link articles, where Unread detects that one article is a link to and comment on another article. It will never be present for links. (Details below.)
title: This is the title of the article. It will be present for articles that have non-blank titles. It will never be present for links.
feed_name: This is the name of the feed from which the article was found. It will be present for articles from feeds under most circumstances. It will never be present for links. It may not be present for an article created via Unread’s Save to Unread functionality. It also may not be present for an article from a feed to which you are no longer subscribed.
summary: This is the body text that appears in the article list when Show Summaries is enabled. It will not be present if Unread is unable to generate a summary of an article. It will not be present for links.
author: This is the name of the author of the article, if specified by the feed. This will be present for some articles. It will not be present for links.
date: This is the date of the article as an ISO 8601 formatted string. This will be present for all articles. It will never be present for links. A Get dates from action in a shortcut can convert this string to a date that subsequent actions can manipulate. A Show Date sample shortcut shows an alert with the article date in a different format.
selected_text: The selected text in the article, if there is any. This is present for an article when it is open and text is selected. It is never present when invoked on an article from a context menu in an article list. It is never present when invoked from an article list. It is never present for a link.
selected_html: The selected html in the article, if there is any. This is present for an article when it is open and text or other content is selected. It is never present when invoked on an article from a context menu in an article list. It is never present when invoked from an article list. It is never present for a link.
link_text: This is the plain text content of a link, such as “click here”. It will be present for some links, but not for articles. It will not be present for a link that has no inner text.
Explanation of URLs
The shortcut input dictionary includes up to three URL keys for each article: url, article_url, and linked_article_url.
For traditional articles, the article_url value will be equal to the url value and the linked_article_url will not be present.
For most link articles, the article_url and url values will be equal, and will be the URL of the article published by the website that publishes the feed. The linked_article_url value will be the URL of the article to which the feed publisher links. For example if a Daring Fireball article links to a New York Times article, the article_url value and url value will be the Daring Fireball article URL, and the linked_article_url value will be the New York Times article URL.
For some link articles, specifically those from Hacker News and from lobste.rs, the url value will be equal to the linked_article_url value instead. This is because the Hacker News or lobste.rs article webpage is just a comments page, and customers rarely want to share or save the link to the comments page. When you do want the comments page, use the article_url value.
Sample Shortcut
This sample shortcut saves the link or article to GoodLinks. Running this shortcut requires downloading the GoodLinks app from the App Store.
To use this shortcut from Unread on Mac:
- Install the shortcut if you have not already done so.
- Download GoodLinks from the App Store if you do not already have it. This is a free download. (GoodLinks is required for this particular sample shortcut, not for running shortcuts in general.)
- Open the Shortcuts pane of the Settings window.
- Add a shortcut with the shortcut name “Save to GoodLinks”. Set the run mode to Background.
- Open an article in a main viewer window.
- Choose Save to GoodLinks from the Article menu. The first time you run this shortcut, you may be prompted for permission to run GoodLinks actions.
To use this shortcut from Unread on iPhone or iPad:
- Install the shortcut if you have not already done so.
- Download GoodLinks from the App Store if you do not already have it. This is a free download. (GoodLinks is required for this particular sample shortcut, not for running shortcuts in general.)
- Open Unread’s Settings screen.
- Choose Shortcuts under Premium Options.
- Tap the Add Shortcut… button.
- Enter the shortcut name “Save to GoodLinks”. Leave the Reopen Unread setting on.
- Tap the Save button at the top right.
- Navigate to an article and open that article.
- Swipe the screen to the left and choose Save to GoodLinks from the resulting menu. The first time you run this shortcut, you may be prompted for permission to run GoodLinks actions.
Adding Shortcuts to Unread
On Mac, shortcuts must be added to Unread via the Shortcuts pane of the Settings window. On iPhone and iPad, shortcuts must be added to Unread via the Shortcuts screen (from the Settings screen under Premium Options). Each shortcut has these attributes:
Shortcut Name: This must be identical to the name of the shortcut as saved in the Shortcuts app.
Run Mode (on Mac): When set to Background, Unread will open Shortcuts in the background. If the shortcut is not run successfully, Unread will show an alert with an appropriate error message. When set to Interactive, the Shortcuts app will come to the foreground. The Shortcuts app will report any errors it encounters. Interactive mode is appropriate for a shortcut that opens another app and leaves the user to complete a task in that other app.
Reopen Unread (on iPhone and iPad): The Shortcuts app always comes to the foreground when Unread runs a shortcut. When this setting is on, Unread will come back to the foreground when the shortcut completes. If running the shortcut is unsuccessful, Unread will still come back to the foreground and will report the error. When off, the Shortcuts app will report any failure to run the shortcut. Turning this setting off is appropriate for a shortcut that opens another app and leaves the user to complete a task in that other app.
Keyboard Shortcut: Optionally choose a keyboard shortcut that will run the shortcut on the current article.
By default the ability to set a hardware keyboard shortcut is not visible on iPhone. You can enable it by swiping left from the Shortcuts Settings screen and choosing Show Shortcuts from the resulting menu.
Show Shortcut Dictionary
The share sheet or share popover of every article and every link has a Show Shortcut Dictionary item. This shows the set of key-value pairs that will be sent to a shortcut when run on that article or link.
Rerun Shortcut
After running a shortcut on Mac, you can run the same shortcut on the same article or link again by choosing Rerun Shortcut from the Edit menu or using the ^⌥⌘Z (Control-Option-Command-Z) keyboard shortcut.
After running a shortcut on iPhone or iPad, you can run the same shortcut on the same article or link again by choosing Rerun Shortcut from the swipe left menu of the Shortcuts Settings screen, or by using the ^⌥⌘Z (Control-Option-Command-Z) hardware keyboard shortcut.
When rerunning a shortcut this way, Unread will add a unique identifier as a query parameter to each URL in the dictionary it sends to the shortcut. This is useful when writing and testing shortcuts. It prevents some apps from ignoring a request to save the link because it looks like a duplicate.
