Principles That Determine the URL Scheme Returned by `Copy Link` for a Given App

When you call Copy Link on a linkable item in a given app, Hookmark returns a link consisting of the item’s name and an address (URL) to access that item. Hookmark will use the custom scheme for the app, shown in its Scripts preferences pane, or the default script (also shown in that pane). This document describes the rules that determine the scheme of the URLs returned by default by Hookmark for items of a given app or service — for example, whether it is a hook:// URL scheme, the app’s native URL scheme (such as OmniFocus://), or some other URL scheme. This also lists Hookmark’s custom sub-schemes.

The first thing to note is that for any given app with which Hookmark can integrate, Hookmark Pro users can configure the URLs that are returned by Hookmark via the Gear menu > Preferences > Scripts tab. This means that users are not bound to Hookmark’s defaults. The current document, then, discusses the URL schemes that may by default be returned by Hookmark’s Copy Link.

Principles for selection of the URL scheme returned by Hookmark

This section describes the principles used by CogSci Apps for determining the scheme of URLs returned by Copy Link (and Copy Markdown Link). The expression “in the context of this app” means “when Hookmark is invoked while this app is in the foreground of macOS”.

  1. If an app offers a way to generate URLs to its resources, and if the app robustly serves its URLs, then in the context of this app, Hookmark’s Copy Link command should return the URL generated by the app. For example, OmniFocus provides a Copy Link API that returns links with OmniFocus:// URLs. OmniFocus robustly serves OmniFocus:// URLs. So Hookmark uses them. (FYI: in the majority of cases where an app programmatically serves a URL scheme, Hookmark uses it.)
  2. If an app’s resources are Finder manipulatable files, and the app can open its files directly but does not have its own URL scheme, then in the context of this app, Hookmark’s Copy Link command should generate hook://file/ URLs in its context. BBEdit, OmniGraffle and OmniOutliner are examples amongst many.
  3. If an app can generate its own URLs but cannot necessarily serve them robustly (particularly in the case where the file is modified by the user directly in Finder), and if the app does not use its URLs in a mobile setting, then (other things being equal), in the context of this app, Hookmark’s Copy Link command may generate hook://file URLs. An example is the excellent personal information manager, EagleFiler. EagleFiler has a Copy Link function that generates x-eaglefiler://open?… URLs. Files in EagleFiler are directly accessible in Finder, but moving them directly in Finder (outside EagleFiler) breaks their URLs. (See also Other considerations). In addition, EagleFiler users often open these items in a third party app (e.g., an external PDF reader) where the EagleFiler URLs of these items are not available; so in this case, Hookmark by default generates a hook://file/ URL.
    • However, where Hookmark uses the hook://file/ scheme for such an app, CogSci Apps may publish an alternative integration script bundle whose ‘get address’ script returns a URL in the app’s native URL scheme (e.g., x-eaglefiler://open?…). This is what CogSci Apps did for EagleFiler and Curio. Hookmark Pro users can copy and paste the published integration bundle into Hookmark’s script for the app. This means that Pro users can easily configure Hookmark to return URLs in the app’s native scheme or the hook://file/ scheme.
  4. If an app cannot generate URLs to its resources but does provide some means of identifying its resources, Hookmark may create URLs of the form hook://<app-specific-sub-scheme>, where the sub-scheme is specific to the app. hook://outlook/, hook://notes and hook://spotify/ are examples of this.
  5. For groups of related apps that can, in principle, open the “same” information resource, but that cannot generate or consume URLs of a generic format, Hookmark may define a generic scheme of the form hook://<function-specific-sub-scheme>. hook://email is an example: compatible email apps (Apple Mail, MailMate, Airmail 3, etc.) all provide an API to get the current email’s RFC compliant ID, and to open emails by this ID, but do not provide a generic URL. Because macOS does not provide a standard configuration for email (unlike for web browsers), Hookmark creates hook://email links and serves these links by translating them to the email app specified (in Hook) as the default for such links. See favorite apps.
  6. Hookmark may also provide schemes for additional services and functions it provides. hook://search/ is a prime example of this. These links may be manually created by users or automatically by software. Activating these links triggers a Spotlight search for files that match the search criteria.

Qualifications

The above are simply principles. Please note:

  • Other specific considerations may be pertinent to particular apps and hence affect the scheme of URLs Hookmark returns. They may be discussed in our documentation for the specific apps, and added to future revisions of this document.
  • Ultimately, to see how Hookmark returns URLs for a particular app, the user may try Hookmark’s Copy Link in the context of that app, examine the script for the app in the Script Editor pane, and/or visit the documentation about the app on this website and the Hookmark forum).
  • As noted above, if they wish, users can configure Hookmark, via the app’s “get address” script, to return a different URL scheme from the one provided in the Hookmark app.

Custom hook:// sub-schemes

Like many other apps, Hookmark defines a scheme of its own. It is hook://. Hookmark supports a particularly rich collection of sub-schemes, most of which were mentioned above.

  • hook://addressbook: For Apple’s Contacts app.
  • hook://email/: for linking to emails in an email-client agnostic way (based on RFC email ID).
  • hook://file/: for linking to files in Finder.
  • hook://ical/.
  • hook://macJournal/.
  • hook://notes/ for Using Hookmark with Apple Notes.
  • hook://outlook/, hook://outlook/task/, and hook://outlook/note/. However, note that Outlook’s IDs are not proper URLs.
  • hook://search/: triggers a Spotlight search.
  • hook://slack/.
  • hook://spotify/.
  • hook://tbx/ (for accessing Tinderbox items).

Other sub-schemes may be defined in the future.

This section will be augmented with links to web pages that discuss the specific sub-schemes. Meanwhile, try searching the documentation or forum — using a search engine or the 🔍 glass above.