Every database, group, or document in your DEVONthink database has a URL (uniform resource locator) associated with it. While web URLs typically begin with http:// or https://, DEVONthink's URLs take the form of x-devonthink-item:// followed by a long alphanumeric ID. These are most commonly used for backlinks and deeplinking, even with external applications. But item links can also be used as a type of automation when extended with URL parameters.
You can get this item link manually by selecting a document or group and choosing
Edit > Copy Item Link. You then can manually extend the copied URL with the following parameters, as needed:
-
app: Used in conjunction with the openexternally parameter, specify the name of the app to open the referenced file with, e.g., x-devonthink-item://E35A4AFF-BD90-4131-9D54-62849E0EF4DE?openexternally=1&app=preview.
-
length: Specify the number of characters from the start parameter. Used in selection links.
-
openexternally: Opens the referenced item in the system default application, e.g., opening a PDF in Preview. Used with a value of 1, e.g., openexternally=1.
-
opentab: Opens the referenced item in a new tab in the current main window if a document is already being viewed. Used with a value of 1, e.g., opentab=1
-
page: Opens a PDF to the specified page. Usage: page=<integer>.
-
reveal: Reveals an item in the item list instead of opening it in a new window. Usage: reveal=1.
-
search: Directly jumps to the first occurrence of the search string in the specified document. Usage: search=<string>.
-
start: Specify the starting character on the current page. Used in selection links.
-
time: Directly jumps to the specified time in seconds in a video or audio document. Usage: time=<float>.
|
Example:
x-devonthink-item://<recordID>?reveal=1
x-devonthink-item://<pdfID>?page=5
x-devonthink-item://<textFileID>?search=iPad%20Pro
x-devonthink-item://<movieID>?time=43.5
|
|
Note:
The first parameter after the ID is always added after a question mark (?), additional ones after an ampersand (&), and any values must be percent-encoded.
|
Terminology
Manually getting item links can be useful for some hard-coded cases, but there are many times you want to get them programmatically. There are two AppleScript properties for a record related to item links:
-
reference URL: This is the item link as described above.
-
UUID: This is the unique identifier of the item, i.e., the long alpha-numeric string in the reference URL.
Here is an example of getting and using an item link to create a Markdown compliant link on the clipboard:
|
Example:
tell application "DNtp"
set recordName to name of content record
set recordURL to reference URL of content record
set the clipboard to ("[" & recordName & "](" & recordURL & ")")
end tell
|
The terminology for using item links can depend on the capabilities of the application you're scripting. Here is an example, using a hard-coded URL, with an application that can open URLs:
|
Example:
tell application "Opera"
tell window 1
make new tab with properties {URL:"x-devonthink-item://929D101B-35AC-474C-801C-D8818C48DB80?line=125"}
end tell
end tell
|
P.S.: For the shell scripters, the URLs can be used with an open command.
|
