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

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…

Hi Frederiko,

Once again I’m here to appeal to your generous help.

In my case I use this script as a tool for my literature review: read and annotate documents - notes, ideas, etc…
First I have two main groups/folders called “Primary Sources” and “Secondary Sources”. Inside these groups I place/index each Document in one sub-folder/group (for example: “Leach 1997”).
When working with one document, I’m interested to place all related annotations inside the same document folder (or in a group inside that folder).
For me this is the better way to organize my work.

Considering the script I ask:

--DEFAULT LOCATIONS -----------------------
-- The default location where document groups and annotations are stored
property groupLocations : "Inbox/annotations/groups"
property annotationLocations : "Inbox/annotations/text"

1. It’s possible change the “default locations” to the same path of the document?

2. Why the script create two folders (“groups” and “text”)? Are both necessary? Can the script work only with one (“group” for each document)?

Thanks for your patience and generosity.


Hello Paulo

The two folders serve different purposes but contain replicants of each other. The “groups” is intended to be a “hidden” folder. You should never need to go into it. It contains a groups that are unique to every annotated document. When you click the URL link of an annotated document, it takes you to this “hidden folder” which contains replicants of every annotation to that document, no matter where those annotations are actually kept. This hidden group is already replicating to some extent the functionality you want by linking the document to the annotations. You find it by clicking the URL link at the top of a document.

The “text” group is the default location for text annotations - that is an easy place to find all annotations. Checking the “Set annotation location checkbox” in the annotation pane brings up a standard group selector panel which allows you to choose any location to save your text annotation. You could check the “Set annotation location” checkbox and choose to store your annotation in the same group as the document. I can see however if you wanted that as the default location that it could be tedious.

No by default you cant do this. I have however produced a modified version of the script which will do what you want. You can download it here. (This is not intended for general use but only for Paulo’s specific request)


Hi Frederiko,

Many, many thanks for the ‘exclusivity’ :smiley:
Deeply grateful.

If I’m not wrong, the difference is: instead the annotations go to the default “text” group they remain on the same group/folder of the document. Right?

Considering the implicit process, when finished the review of document the result is a folder with the document and the annotations (single annotations). In my workflow the logic of ‘single’ annotations is important: tagging, comments, etc. But at the end I feel the missing of a general view, a kind of “scrivening mode” (Scrivener) to view all the ‘single’ annotations together but keeping all the singular metadata (links, tags, etc.) - just a more practical view mode (different from the “Merge”). Maybe a feature to one future DTP version :smiley: :bulb:

Once again, thank you.

Best regards,


I support the request of a Scrivener-like contiguous view of documents in DT. But by now Annotation Pane has become such a central part of my work in DT that I’m worried it may not work in the next version!

I have a question as well: So far, all the created annotations are excluded from search, classification and see also. I have tried changing the permissions to the general text folder which contains all replicates. To no avail, so I carry on changing this setting manually to several notes from time to time. Is there a way I can change this automatic behaviour in the script?

Thanks so much,


Agreed, it would be a great feature. Maybe something as straightforward as being able to edit and view selected rtf/ formatted note or markdown files as a contiguous file?

Pleased its working for you :smiley: Its so central to my workflow too that I will do what I can to keep it working.

Are you using the latest version of the script (305)? This was a problem which was fixed a few versions ago (I hope) and I am not seeing it. Only folders in the “annotations/groups” folder are excluded from see also, etc which is the desired effect. The annotations and the “annotations/text” folder should definitely not be excluded. (EDIT: realised from your previous posts you are using 305. I will have to do more testing :frowning: )


Let’s make a force to the DT team consider this feature! :wink:

Hello Frederiko,

I’m here once again…

Allows me put one scenario with some problems…

I’m interested in organize my notes, ideas, annotations, etc., with tags. Tagging is a fundamental resource to my workflow…
In a big project we can imagine the large number of tags. So, for better organization I adopt the solution of “tag groups”, naming this groups by topics: “Names”, “Concepts”, etc. Inside each group we have the related tags (the ‘real’ tags)! “Names” > “Adorno”; “Benjamin”; “Lukacs”; …

Define “Special Groups” and “Extra Groups” on config.scpt
With the ability to use until 5 tag groups on Annotation Pane (2 special and 3 extra) I defined this groups on config.scpt (note: I defined these groups before installation, i.e., before copy “Annotation Pane.scptd” to “Scripts Folder”)

Using tags
On tagging something, the goal are the ‘real’ tags, not tag groups. Because of that I prefer to exclude ‘tag groups’ from… tagging!
Using the previous example, I’m interested in the tags “Adorno”; “Benjamin”; “Lukacs”; … but not in “Names”. So, in the group “Names” I enable the option “Exclude from…tagging”.

The problem
The next time I use the Annotation Pane - for example to tag an annotation with some tag on tag group “Names” - this is the behaviour:
1 - DT create another tag group with the same name (a second folder with name “Names”) with the option “Exclude from…tagging” disabled;
2 - the ‘real’ tag (an existing tag - for example “Adorno” - or a new one - for example “Cacciari”) is placed on the previous group (for example, on the original group “Names” - the group with the option “Exclude from…tagging” enabled)
In this example, the annotation is tagged on tag “Adorno” placed on group “Names” (that is excluded for tagging) and tagged on tag “Names” folder enable for tagging:

“Names” > “Adorno"

There is a solution to this problem? With the Annotation Pane script there isn’t a possibility to exclude from tagging the tag groups?



Hello Paulo,

I didn’t realise you could exclude tags from from tagging! I can’t see a purpose for this.

The purpose of tag groups in the Annotation Pane is as an organisational tool. Tag groups put tags which are of a similar type, such as names or places, into a related place. This makes consistent tagging, and searching on those tags, easier. As Bill has pointed on this forum, the biggest reason for failure of tag systems, is that its very difficult to tag consistently. Tag groups are supposed to help with this by putting logically related tags together.

You seem to be trying to do something else with tags but I don’t understand what it is.

I do not understand what the problem is. What do you want to achieve? Could you post a screenshot to help me understand.

It appears you are creating several tags/tag groups with the same names. I haven’t tried it, but I think these duplicate tags would simply be replicants of each other.


Yes, I’ve been using version 3.05. For what I have checked, replicants share the same properties. When I change manually the setting of an annotation in the annotations/groups folder to be excluded from See also, it changes as well in its replicant in the annotations/text folder.

If the properties of the annotations/groups folders are inherited by an annotation file, according to the above test its replicant in annotations/text will be changed as well. If this is so, I don’t know what happens when two folders have conflicting property settings.

If the properties of a folder are not inherited by files, I do not know how they affect by themselves searching in DT.

I’m just trying to be of some use. If the above is not correct and I can be of any help, please let me know: If I knew the code that was changed to correct this behaviour, I could check if it is right in my copy of the script.

Hi Frederiko,

Let me try to be more clarifying (write in a foreign language isn’t my great ability). Let’s do it step by step (with images).

step 1 - The structure of my Database “TESTE”
I want to work with 5 main tag groups: “1.Tag Group1”; 2.Tag Group2"; “3.Tag Group3”; “4.Names”; "5.Concepts”.

step 2 - Define “Special Groups” and “Extra Groups” on config.scpt
With the ability to use until 5 tag groups on Annotation Pane (2 special and 3 extra) I defined this groups on config.scpt (note: I defined this groups before installation, i.e., before copy “Annotation Pane.scptd” to “Scripts Folder”)

step 3 - tag groups vs folders

As you mentioned, I want to use the tag groups as an organisation tool (the ‘real’ tags are the tags inside these folders). So I prefer to see this ‘tag groups’ as a folders. But DT see them also as a tags.

step 4 - exclude tag groups from “tagging"
To solve this, the solution is enabling the option “Exclude from…tagging” (“Info” panel) to the desired tag groups (On the example I do this to the tag groups “4.Names” and “5.Concepts”)

Doing this not affect the tags inside each folder(tag group). As you can see on the next image, the “4.Names” and “5.Concepts” are removed from tag list but the ‘real’ tags don’t.

step 5 - testing the tags with a document
On my test database, “Adorno” is a tag inside “4.Names” folder and “Autonomy” is a tag inside “5.Concepts” folder. If I tag a document with one or both tags, the document remain tagged with only that tags. But, for example, if I disable the option “Exclude from…tagging” on the folder “4.Names” (activated on step 4), then the document acquires one more tag - the tag “4.Names”.
As said before, on my database the ‘tag groups’ works like organization folders. So, I adopt the solution “Exclude from…tagging” in these folders.

step 6 - testing the tags with the Annotation Pane
Let’s try the same with the Annotation Pane.
In a document, select text and launch the Annotation Pane.
(Remember: now all my tag groups are excluded from tagging)
step 6.1 - testing the tagging only with ‘special groups’
On the example I assign the tag “Adorno” on “4.Names” and “Autonomy” on “5.Concepts” (and add a new tag “test1” on “5.Concepts”).

The result is perfect: the new annotation document is classified with the three tags and everything runs fine on the database tags structure - the tag “Adorno” is activated on the group “4.Names”, the tag “Autonomy” on group “5.Concepts” and the new tag - “test1” - is created inside this group.

step 6.2 - testing the tagging only with ‘extra groups’
(Remember: now all my tag groups are excluded from tagging)
I have three 'extra groups’(the maximum allowed on the script): “1.Tag Group1”; 2.Tag Group2"; “3.Tag Group3”. Inside “1.Tag Group1” I have the tag “extratag”.
Let’s run the Annotation Pane.
On the example I assign the tag “extratag” on “1.Tag Group1” and create a new tag “Benjamin” on “2.Tag Group2”:

The result is a disaster: the tags are affected to the existent groups (“extratag” on “1.Tag Group1”; “Benjamin” on “2.Tag Group2”), but are created new independent tags - a new “1.Tag Group1” and “2.Tag Group2”.
(Note: As you can see I use personal icons on my database, but I leave the original icons on this steps precisely to differentiate the results)

Now, my new annotation document is classified with four tags:

There something happening with the “extra groups” in comparison with “special groups”. As we can see there’s a different behaviour: the “extra groups” have problems with tag-groups/folders excluded from tagging.