Annotation Pane (Annotation with Links, Notes, Tags v3)


When I move into Scrivener the notes taken with this script, I have the link to the pdf, but not the link to the annotation itself that I wrote, which I certainly need. Am I missing anything here or wouldn’t it be good for such a link to be included in the body of the note as well?

A great addition to DT, by the way.


I’ve noticed that the page number in the prefix to the title of the note sustracts one to the pdf page number. However, the link inside the body of the rtf annotation is the same as the pdf page number. I am thinking of modifying it but, being such a carefully thought out script, I suspect there is a good reason for it. Though I don’t get it.

How are you putting the annotations into Scrivener - copying and pasting or importing?

Very interested generally in DT <-> Scrivener workflows

You can always go back to the original annotation by using the ‘annotation group link’ in the rtf and then choosing the annotation from there. Point taken however and I will see how a link back to the original annotation can be inserted into the rtf.

You are correct. This is an inconsistency I plan to rectify.


Neither of them. I drag the note from the Annotation Pane and drop it in Scrivener’s reference panel for links. There they are clickable and conveniently viewable with quicklook whilst I am in the outliner view.

The problem with this is that a later manual change to the file name will disconnect the link -what gets now linked in the reference pane is the file path (file:///) not the hyperlink (x-devonthink-item://).

Having a DT hyperlink inside the annotation will make it easy to locate the file when its name has changed due to later modification and refinement of the annotations in DT.

Only in the body content of the annotation. For the link when clicking the file name, Annotation Pane does well using a path link. Unlike hyperlinks, path links can be viewed with quicklook, and this is very convenient in Scrivener’s reference pane.

I also wonder if it would change any of the workings of this great plugin to move groups and texts folders manually to a new database, and the annotations in the groups folder to external folders. Keeping them in another database, separated from the long pdfs they link to, might be better for DT’s See also. And keeping them externally, they’ll be accessible to Spotlight

Also, and only it doesn’t change its workings either, if it would it be easy to change the Annotation Pane’s script for the groups folders to get the name from the pdf they refer to, instead of their DT’s hyperlink.

I played around a bit with Scrivener’s reference pane and I can’t find a good solution. The problem is that when the file name changes Scrivener will not be able to find the file and hence a link to the original annotation in the text will be of no use. The best I can suggest is adopting a strategy of flagging or labelling any files whose links are put in Scrivener to alert you not to change the name.

This would not work for a number of reasons. Thanks for the input though, the point you raise is very valid. For this reason v303 turns off the classification and indexing of the annotations in the groups folder. They are effectively invisible to DT’s indexing and classification. The groups folders take almost no space at all because they contain only replicants.

Turn on “create spotlight index” in the database properties to make the database searchable by spotlight.

Maybe I have missed a use case but the groups folder in intended to be effectively invisible. There is no good reason to get a source document’s group folder by going to annotations/group. The way to get to a source document’s group folder is through the source document’s url link.

Thanks for taking the time to give input jmm (and those of others in this thread and who have emailed me). It has been invaluable in tracking down bugs and in producing a help file which should hopefully be in a future version.


Hi Frederiko,

Once again, thanks for your work.

I have some observations to make, not as a negative viewpoint but as a contribution to improve this great tool.

1. v303 - some problems :exclamation:
1.1 - “side panel”
First, the number of selected words is limited. Some of the text is missed and not appear on side panel.
Secondly, some of the characters not appear. Not only special characters as " or # but all the punctuation.
1.2 - annotation/notes field
Remains the problem with the paragraphs: unlike the version v2, the result is a continuous phrase with the expression “[return]” in the paragraphs’ place.

2. a useful extra field :bulb:
In some cases we work with a reference manager. These references have some important information. Thence, I ask if is easy add a new field in the Annotation Pane (optional) to introduce the link to the reference. For example, Bookends or Papers (Endnote no) have the feature that allows create a “link” to access to the reference.

3. Keystroke :blush:
Once you said:

I’m a newbie not only in DT but also in the mac world… and in System Preferences>Keyboard I didn’t find any reference to this script! How to create this keystroke?

Thanks for your patience and generosity.


Hi, Paulo. I can reply to the above question. You first open the Automator app, choose Service and put the script into a Run AppleScript action. Later, open System Preferences, choose Keyboard settings, go to the Shortcuts tab and in Application shortcuts, assign the hotkeys, as it is graphically explained here.

Alternatively, you can use any launcher that supports executing AppleScripts and setting global hot keys, such as FastScripts.

Thank you, Frederiko. Points taken. I’m now tagging some annotations to indicate their name should not be changed. I have also turned Spotlight on in the DT database properties, which I think it allows searches in ~/Library/Caches/Metadata/ The problem with this is that files there are devoid of tags -my main organization criteria in DT.

Just in case it works for Paulo as well, I will mention that I tag all annotations with their Citation ID from my reference manager. When I select the citation tag I get a view in which it is possible to browse, read and write in the annotations without many clicks. The same view I would get from the annotations’ group folder (as Three Panes, Widescreen). I find this view more confortable to work with than the icons’ view reachable from the annotations’s source documents’ link. I include an image.

Since I don’t know much about DT’s AI, I wonder if it makes a real difference to restrict pdf file names to their short citation ID, although I always forget which title Author Year stand for. The thing is that when searching, annotations will come up due to the wordings of the descriptive pdf titles they include in their text content, although particular annotations may not focus on the searched topic at all.

For the same reason, I also wonder if long pdfs and short annotations should be kept in different databases.

I didn’t realise this but I tested it and you are correct. The alternative might be to put annotations in an indexed file which would make the keywords available to spotlight.

A newly created group inherits its window style (icon, column split, three panes) and the viewable columns from it parent folder (when opened as a separate folder). This makes it very important to set up the folder structure carefully before you start, if like me, you use different views for different folders. So instead of the icon view that you are seeing when you select the annotation group from the source link, I have the folder set up to show me a split view with only the relevant columns open that I need. This is done by setting up the correct view in the annotation/groups folder.

It is probably because I am not following your methodology properly but your system seem on first glance to be quite clumsy and not conducive to easily finding information.

I would set it up a little differently :-

  • The title would be the name of the pdf document
  • The author and the year would be tags, or parent folders
  • The annotations title would reference something relevant to the annotations, such as the first few words of the selected text. This would help in search and AI to identify the relevance of a searched document
  • The full citation should appeal in the annotation text so there is no need to reference this information from the source document

I use my folder structure to automatically generate the citations while I am writing in OmniOutliner using variation of this script: [url]Cite&Write with OmniOutliner]
Just a suggestion because when I was in academics reference managers hadn’t been invented yet.

Reference back to the citation manager

Paulo mentioned that a reference back to the citations manager (such as Endnotes, or Bookends) would be useful. I don’t have any experience with citation reference managers so I am going to experiment and see how best to create a link back to the citation manager. This would seem to be the best answer to jmm’s problem too.


Such a helpful and thought-provoking exemplar of Pashua-based UI, quite apart from anything else.

Many thanks !

@ Frederico: I was also in academics before citation managers had been invented, churning out bibliographies and course suyllabi that were funded and distributed by the National Science Foundation.

But at least we had advanced from clay tablets to shoeboxes of index cards containing handwritten information. :laughing:

I love computers, DEVONthink and your scripts!

I’m also an enthusiast of Annotation Pane. To the point of convincing me to come back to DT. I’m slowly moving my data from good but inflexible Atlas.ti and MaxQDA, so I still have a tendency to rely more on structured organization than on freer search.

The problem I had of getting the icons’ view was due to not searching from the top most folder, i.e. Inbox, but from the annotations’ groups or text folder. I record my mistake here in case another user experiences the same.

Another convenient way to quickly browse annotations is Cover Flow, but DT doesn’t seem to focus rtfs as immediately as Path Finder.

As for the reference manager, thank you for your consideration. All I need from it is the citation ID, which I already have in DT, both as a tag and at the beginning of the pdf’s title. Therefore, even if I ever want to have a look at a record, I don’t see it as a significant part of my workflow.

Thank you as well for sharing your methodology, Frederiko. What you have described is not too different from mine, what may not be clear because of the language. The main difference might be that I include a good number of keywords in the annotation title, so that I can search in Spanish as well if the source document is in English. As a side note, I think it would make a big difference to newcomers if DT made available a few videos not only about the functions but about real power uses of the app.

I have moved externally the text folder to have it indexed. And back again inside the database when I’ve realised I shouldn’t risk loosing the hyperlinks among annotations I include in some of them.

Maybe as a result of the above, now the new annotations I make have their properties set to be excluded from Classification, Search and See also. I’ve checked that both the annotations’ texts and concerned group folders are not set to exclude. Any idea about how I could change this behavior?

I understand why you got an icon view. One of the placeholders in the rtf is %annotationGroupLink%. This places a link in the rtf called ‘Source Document annotations’. Clicking ‘Source document annotations’ will display an icon view of the annotations tag group which is not very helpful in this context. Instead try right clicking on ‘Source Document annotations’ and selecting open link. This will open the annotation tag group in a new window and respect the layout settings of the group. The way devonthink layouts interact can be complex because of all the permutations.

You should not lose the hyperlinks if you move the rtfs into an indexed folder but I haven’t tested it extensively so I can’t recommend it.

No, it wasn’t anything you did. There was a bug in the code which I have fixed in v305. To fix the exclusion simply select all the annotation texts and and choose ‘show info’ from the right click menu. From there you can reset the properties of all the selected files at once.

Thanks Paulo. This has been fixed in v305.


I had not seen this possibility. Thanks again.

As for the automatic exclusion of annotations from search… in v305 it seems to be still there. I recall that you mentioned that v303 turned off the classification and indexing of the annotations in the groups folder. For what I have tested manually, when I change this setting in an annotation in the groups folder, it also changes in its replicate in the text folder. Could this be the issue?

Whatever the case, this is not much of a problem to keep using Annotation Pane, as the setting can be changed manually for the time being.

This is a short script which will work with the documents produced by the Annotation Pane and the Document Review Pane to produce a sheet of all the selected source documents, annotations and their related metadata such as the extra groups defined in config.scpt.

It will produce a sheet that looks something like this:

sheet of docs and annotations.jpg

Sheets are easily exported to Excel, Numbers or a variety of other formats

The Sheet has the following columns:
Item no. A sequential number incrementing for each row
Running PDF page Number The page number of the pdf if all the pdfs in the sheet were numbered sequentially. Other file types are ignored. Useful for producing indexes.
Date The creation date of the document.
Document name The name of the document.
Spotlight comment The spotlight comment of the file.
Page Number The page number that the document references if its an annotation OR the Bates number if such a number is detected in the the spotlight comment.
Source Document The name of the source document if the document is an annotation.
…Tag columns… The tags of the file for each of the specialGroup1, specialGroup2 and extraGroups tag groups as defined in the config.scpt file.

[20150519] Running page number added

Index docs and annotations (32.1 KB)

I haven’t yet taken the plunge with this updated script, though I’m excited to do so.

One quick question…

I know it’s unlikely, but I’m wondering if this annotation script might somehow work with DEVONthink To Go 2.0?


Not possible. Nothing on iOS works with AppleScript or the other tools used in Frederiko’s tool. There are plenty of annotation tools on iOS that work with DTTG2. Or, you could learn Python or Swift and write your own :smiley:

Yeah, I figured. Never hurts to ask.

Follow up question… Are you saying that there are other annotation tools on iOS outside of DTTP that one could use w/in DTTP – to compliment (or enhance) DTTP annotation? Or are you just saying that DTTP has good annotation tools?

Just wondering if there’s any way to add tags from DTTP-annotated documents that would transfer into the OS X version of DTP.

Any suggestions? Thanks!

Ooops! Just realized that I didn’t properly articulate that idea. What I meant to say (or ask) was …

Just wondering if there’s any way to add tags from DTTP-annotated documents and include annotations to those tags (in the way that this script provides) that would translate from iOS / DTTP to the DTP / OSX app.

Any ideas or suggestions? Happy to even consider a hack solution.

Thanks again…