Is Item Link syntax documented somewhere?

Yesterday, I saw something mentioning the ability to extend the basic inbound DT link like so:


IIRC the page argument only works for some formats such as PDFs (from experiment the numbering is zero-based, i.e. use a value one less than the PDF page number you actually want).

Of course i should have put the reference in DT before I moved on! I’d assumed such important stuff would be in the manual or a support FAQ/Knowledge Base but I can’t find anything.


Unfortunately, there is no FAQ or Knowledge Base – other than the tutorials, Help, and this forum. There’s no consolidated, well organized DEVONthink wiki. (Something like the excellent reference “aTbRef” for Tinderbox, maintained by a volunteer, would be welcome in the DEVON-world, IMO.)

FWIW, in the case of x-devonthink-item:// (two slashes only, BTW), there is another option for links to PDFs:

x-devonthink-item://1F606F27-9815-41D8-B6B9-6E8D95FD2C5C?search="my string"

Thanks. I’ll give that a try. Some users at the Tinderbox forum (many seem to use TB with DT) were asking about the syntax so I thought I’d fill in the blanks.

Thanks for the kind words about aTbRef. :wink:

BTW, the page link for a PDF is placed on the clipboard when one control-clicks a PDF page thumbnail in the PDF display sidebar – or anywhere in the body of the PDF – and selects Copy Page LInk from the contextual menu.

Clicking here

places this on the clipboard:


Useful - thanks. As you may have guessed, I’m thinking about users wanting to tweak references already stored elsewhere by doing things like adding the ‘page’ parameter.

What I’ve accumulated so far:

  • There are 2 extra parameters ‘?page=’ and ‘?search=’ that may be appended to a basic item link.
  • These extra parameters can only be used for PDF resources**.
  • Parameters are case-sensitive, i.e. ‘page’ NOT ‘Page’.
  • ‘page’ uses a zero-based count. Thus to target page #4, use '?page=3". Counting up from zero, 3 is the fourth item (0,1,2,3). Also this is the ‘physical’ page number within the PDF not any text page number ‘printed’ on the page. The ‘paper’ page #1 might be PDF page #20 allowing for preface, TOC, etc.
  • ‘search’ is case-insensitive. ?search=Cubert will open the target PDF at the first instance of ‘cubert’, ‘Cubert’ or a word starting with that string. The matched string is highlighted in the open document.
  • Find Next is not enabled for documents opened using ‘search’, i.e. it can’t be used to move to the next instance of the original search string. Not reason that this should be possible, but it would be neat if it did.
  • The ‘search’ string must be URL-encoded, that is, is %-based codes for characters like spaces that can’t be used in URLS. So to search for ‘Cubert Farnsworth’, the parameter you’d add becomes ?search=Cubert%20Farnsworth.
  • Not specifically tested but only one of the above parameter can be used at a time. (I don’t see you’d want to use both but…)

** or does it works for Word docs and other ‘paged’ content, e.g. not HTML pages.

ISTR there are some other code for targeting individual emails. I should add that I’ve no pressing personal need for this but am simply using the info to assist others who do want this. I also cleave to the notion that a feature undocumented is development wasted (hence aTbRef).

Hopefully that will help a few others!

Note, one may find a full explanation in the description of the reference url property of a DEVONthink record (i.e., a document) in a database. The description is found in the scripting definition file (SDEF) for DEVONthink. The particular display below is from the SDEF explorer in Script Debugger. The SDEF can be found in the application package (if the reader doesn’t know what that means, then I’d advise leaving it alone :cry: )

Ah, that’s the reference I couldn’t remember! Thanks. Saw that whilst making a name/item link exporter script the other day.

Interestingly the form of ‘time’ parameter value isn’t given. My hunch is hh:mm:ss, e.g. 00:00:30 for 30 seconds into a movie. IOW ‘?time=00:00:30’.

As kindly pointed out over in the Tinderbox forums, the timecode argument is in seconds. Thus, for 1 mn 20 sec start time use the argument ‘?time=80’). Decimals are allowed; ?time=2.4. My understanding is this only works with movies and not audio files (as at DTP v2.4.1 anyway).

Instead of using the Edit menu or right-clicking a file listing entry to ‘Copy Item Link’ , if you right clicking in a displayed part played movie will create a ‘frame reference’ link with a time code added:


Similarly, right-clicking a displayed part-scrolled paginated document (e.g. PDF) will give a page reference for the currently displayed page:


By way of a reference, and return on the help I’ve received here, I’ve summarised this syntax info here on my aTbRef. Notes were based on using DT Pro v2.4.1 on OS 10.6.8.