Hookmark and the papyrus:// URL scheme.
Papyrus registers papyrus:// on macOS, iPadOS, and iOS. This page is the public contract for it, so link-management tools can integrate without asking. There are three entry points: a link to a paper, a link to a notebook, and an x-callback-url query for whatever the user is looking at right now.
Hookmark
Hookmark links a document to the notes, tasks, and emails that belong with it. Papyrus supports it the way Hookmark wants an app to: every paper and every notebook has a permanent address you can copy, and Papyrus can answer the question “what is the user looking at right now?”
The workflow it enables is the one researchers ask for — read a paper in Papyrus, press Hookmark's hotkey, and hook it to the manuscript section, the OmniFocus task, or the email from a co-author that prompted you to read it. Come back to any of those later and the paper is one click away, on the page you were on.
Setting it up today
Papyrus is not yet in Hookmark's bundled script library, so wire it up once in Hookmark Pro's script editor:
- Get Address — Papyrus already puts the link on the clipboard with Copy Link (⇧⌘C), or Copy Link to This Page (⌥⌘C) while reading.
- Get Name and Address — call
get-current-item(below) with ahook:callback; Papyrus replies with the title, the link, and the PDF'sfile://path. - Open — Hookmark opens
papyrus://paper/…directly; no script needed.
An official integration script is on the way: the scheme has been documented here precisely so CogSci Apps can ship one. Until then, the three hooks above cover the round trip.
Other tools
Nothing here is Hookmark-specific. Obsidian and DEVONthink take a papyrus:// link in a note; Shortcuts, Alfred, Keyboard Maestro, and Drafts can both open links and call get-current-item with their own custom-scheme callbacks.
Linking to a paper
papyrus://paper/<paper-uuid> papyrus://paper/<paper-uuid>?page=<n>
For example:
papyrus://paper/9F2C1A54-3E6B-4D0A-8C71-1B9E4F5A6D22 papyrus://paper/9F2C1A54-3E6B-4D0A-8C71-1B9E4F5A6D22?page=7
Opening the link asks Papyrus to open that paper:
| Platform | Behavior |
|---|---|
| macOS | Brings Papyrus forward, selects the paper in the library, and opens its PDF in a reader window. If the paper is already open, the existing window comes forward rather than a duplicate. |
| iPadOS | Selects the paper in the library and presents the reader. |
| iOS | Opens the reader; a paper with no PDF opens its summary instead. |
page is optional and 1-based. When present, the reader opens at that page instead of the saved reading position — including when a reader is already open on that paper, which simply jumps. An anchor that cannot address a real page (page=0, page=-3, page=front-matter) is ignored and the paper still opens: landing on page 1 of the right paper beats an error.
If the current sidebar item or search filter would hide the paper, Papyrus widens the view to All Papers so the selection is actually visible. A link to a paper in the Trash reveals it in the Trash and says so. A link that resolves to nothing — a different library, or a paper deleted since the link was made — reports that rather than failing silently.
Getting a link
Copy Link and Copy Link to This Page put the address on the clipboard as plain text:
| Where | Commands |
|---|---|
| Paper menu (macOS) | Copy Link (⇧⌘C), Copy Link to This Page (⌥⌘C) — both rebindable in Settings → Shortcuts |
| Library right-click menu (macOS, iPadOS) | Reference → Copy Link |
| Reader overflow menu (iPadOS, iOS) | Copy Link, Copy Link to This Page |
| Paper summary (iOS) | Citation & Writing → Copy Link |
| Detail view's Copy button (macOS, iPadOS) | Link → Copy Link, Copy Markdown Link |
| Detail view's Reading card (macOS, iPadOS) | Right-click / touch and hold a bookmarked page → Copy Link to This Page |
“Copy Link to This Page” needs a page to anchor to. In a reader that is the page on screen. Outside one, the only page you have actually pointed at is a bookmark, so the Reading card's bookmarked-page rows offer it and nothing else does.
Copy Markdown Link wraps the same address for pasting into a note:
[Ashish Vaswani et al. (2017) Attention Is All You Need](papyrus://paper/9F2C1A54-…)
The label is Author (Year) Title. Authors follow the same “et al.” rule as the rest of the app, and any part the paper does not have is left out rather than filled with a placeholder — a link label should not invent metadata. Brackets and backslashes in a title are escaped, so a title like “Attention Is All You Need [sic]” cannot end the label early.
Linking to a notebook
papyrus://notebook/<notebook-uuid>
A notebook is a shelf of notes gathered by theme across any number of papers. Opening the link selects that notebook, so its workspace — every note filed on it — is what you land on.
The shape is deliberately the twin of a paper link: same scheme, the host names the kind, the first path component is the UUID. A tool that already parses paper links needs no new rules.
There is no page-style anchor. A notebook has no fixed positions to address — its order is a sort the reader chooses, so an index into it would name a different note tomorrow.
The Markdown form uses the notebook's name as the label, escaped the same way:
[Optics](papyrus://notebook/4B7D0E12-9A3C-4F58-B6E1-2C8D5A9F0E31)
Both are on a notebook's context menu in the sidebar, and in the notebook workspace's own header — on macOS that pane can be a detached window with no sidebar in reach.
Asking what the user is looking at
papyrus://x-callback-url/get-current-item?x-success=<url>&x-error=<url>
Papyrus replies by opening x-success with these query items appended; existing query items on the callback are preserved.
| Item | Meaning |
|---|---|
title | The paper's title, or “Untitled Paper”. |
url | The papyrus://paper/… link. Page-anchored when the answer came from a reader. |
file | The PDF's location as a file:// URL. Omitted for a metadata-only paper or a missing file. |
The current item is the paper in the frontmost reader — and only then is url page-anchored, since a paper merely selected in the library has no page you could be pointing at. Failing that it is the library selection on macOS and iPadOS; on iPhone, which has no library selection, it is whatever the reader or a link-opened summary is showing.
When nothing is open or selected, Papyrus opens x-error with the x-callback-url standard pair errorCode=no-current-item and a human-readable errorMessage.
A worked example — the reply for a paper open at page 7:
x-success://got?title=Attention%20Is%20All%20You%20Need
&url=papyrus://paper/9F2C1A54-…?page%3D7
&file=file:///…/Attention-Is-All-You-Need.pdf
Callback targets must not be web URLs
get-current-item hands the title and local file path of whatever you are reading to an address the caller chose, and a web page can trigger a custom scheme. Papyrus therefore refuses x-success and x-error targets using http, https, file, ftp, ftps, data, javascript, about, or blob — so a page that talks you through an “Open Papyrus?” prompt cannot post your current document to a server.
Every real client of this API — Hookmark (hook:), Shortcuts, Drafts, Keyboard Maestro, Alfred — uses a custom scheme and is unaffected. A refused callback is simply not opened.
Stability guarantees
- The identifier is permanent. It is the paper's sync identity, assigned once when the paper enters the library. Renaming the paper, editing its metadata, moving it between folders, trashing and restoring it, or replacing its PDF all leave the link working.
- It is portable across your devices. The same link resolves on every device signed in to the same iCloud library, so a link copied on a Mac opens on your iPad.
- It is not portable across libraries. It identifies a paper, not a work. Two people who each import the same PDF get different links.
- The format will not change. Additions will be backward compatible;
papyrus://paper/<uuid>andpapyrus://notebook/<uuid>will keep resolving. - Notebook links carry the same guarantees — permanent across renames, reordering, trashing and restoring; portable across your own devices; not portable across libraries.
Unrecognized query parameters are ignored, so links written against a future revision still open the right paper on an older build.
Deliberately not implemented
Creating a paper. Hookmark's create API takes a name and returns a link to the new item. Papyrus creates papers by importing a PDF or resolving a DOI or arXiv ID — a bare name does not identify anything to import, so there is nothing honest to return.
AppleScript. An sdef on a sandboxed SwiftUI app is a large amount of scripting-class work for no capability the x-callback-url API above does not already provide.
One more address exists but is not part of this contract: papyrus://extension-import?id=… is a private wake URL the Safari extension uses to hand a capture to the app, and it may change.