PDF annotation workflow using Highlights app and Hazel


I used to be a user of Sente. I miss that piece of software every because it has the most elegant annotation tools. Over the years, I have tried different methods to emulate the capabilities of Sente.

For reading and annotating, PDF Expert is a fine software. I have used it for some time for reading pdf articles. But, exporting annotations is another story. There is no customization of exporting of annotations. And the result is totally débâcle.

A rather more elegant method of annotation was the one we have in DEVONthink using a script known as Annotation Pane. It is a brilliant script; the closest I get to imitate the workflow I had in Sente.

I have been using Annotation Pane for many years. But, lately, Apple’s PDFKit is getting terrible. As a result, DEVONthink is making many of my files read-only (impossible to edit within DT) to protect the probable corruption.

The great alternative is the Highlights app. It is really amazing annotation tool. The annotations are markdown compatible. So, I am contriving a system to have a fluid and clean annotation system.

The objective is to have a clean annotation file in markdown format with all the images and links back to the original pdf file. The annotation export is live; that means, any new annotation added in the Highlights app will immediately show up in your Obsidian (Devonthink) or any other tool you use to read markdown file.

Another thing I do here is to include the heading of the articles (books) as headings in the markdown note. Including the headings is important to understand the structure of the original article. That is why I want to include them with the annotations.

If you want to try my setup, this is what you need:

  1. Highlights Pro
  2. Hazel

The setup in Highlights

  1. In the Highlights app, you need to turn on save sidecar markdown-file under the General setting. What this means is that your annotations will be exported next to the pdf file you are reading. This is the main engine of the workflow. The sidecar could be either in .md or Textbundle format, depending on the presence of image annotations. If there is an image annotation, the sidecar will be textbundle; otherwise markdown. WE are going to use hazel to process and move those sidecars to our Obsidian vault.

  2. Principle: During the annotation process, I always underline the headings; but highlight the important notes.


  1. Create another folder Highlights inside your Obsidian vault (or indexed folder in DEVONthink). This is the destination of our reading notes.
  2. I assume that all your pdf files are stored in one folder. I call it @articles folder.

Now, go and import your rules their respective folders:

  1. ON the @article folder, you have two rules: The first rule just moves plain markdown sidecars to the Highlights folder. The second one converts the textbundle sidecars to folders before it moves them to the Highlights folder.

  2. Put the rest of the rules (four of them) on to the Highlights folder.
    The first rule simply runs some shell script replacement to properly format the headings. The second rule tells Hazel to go into the subfolders. The third rule (number 6) renames the markdown file, and the final rule trashes the json file (you can leave the json there if you want to).

The result is a beautifully formatted markdown file such as the follows:

I like that the Highlights app puts the highlighted text in quotation marks. A very useful mechanism to avoid the problem of plagiarism. Your own notes come out as regular texts. Any image annotation is also visible because of the /asset folder there which contains the image annotations.


First, thanks for providing another way to work with annotations. That’s always very useful.

But I’m confused about your statement on PDF Expert. A “total debacle”? I’ve used it for years and find exporting annotations to be super easy, super useful. I always export annotations to markdown.

What is it in the PDF Expert export that you find problemmatic? Perhaps you do/use annotations in some way that is markedly different from me. At any rate I’d be interested as I’ve found PDF Expert totally reliable for annotations, and exporting them, for a number of years now.

The term debacle might be a bit of an exaggeration. Excuse me for that. But, the annotation export in PDF Expert clearly has a number of weaknesses in relative to that of Highlights.

  1. I cannot export image annotations. I do use a lot of image annotations to keep complex pictures, tables, and the like appear within my file.
  2. There is no template for exporting. The extra text that comes out such as “highlight”, “underline”, “note”, “page” etc cannot be removed. They add a clutter to the text. A better implementation is to use a formatting as in Highlights: quotation marks for highlights, bold marks for underlined texts.
  3. There is no clickable link to jump back to the original article.
    I think almost every other pdf reader (Skim, Bookends, DEVONthink, etc) provides a better means of exporting than PDF expert.

Interesting workflow, thanks for sharing! Highlights looks like a fine app, but a couple of people here described it as « abandonware ».

It is well stable app. I have mentioned that even version 1.5 is fully functional on the modern version of Mac Os. And, that the annotations are standard adobe compatible, there is no reason to worry about abandonment so far as it is working on your mac.

I also really miss Sente. It was a great app. I find Bookends is getting there though - and their annotation export (with deep links) is pretty wonderful. IMHO it avoids lots of the steps outlined here.

1 Like

I agree, Bookends is getting there. I still prefer the Highlights app for two reasons:

  1. Reading on the mac version of BE is not comfortable. I love Bookends. But, reading pdf in it has never been smooth to me. I prefer dedicated apps.
  2. Bookends cannot automatically sync or export annotations. You need to manually export annotations. The steps I outlined above, once setup; is very efficient. You don’t need to think about exporting at all. You just annotate and hitting “save” is sufficient to get your annotation updated into your Obsidian or other app.
  1. I don’t read on my mac, but rather my ipad - but fair enough! As per 2, if immediate sync is the priority you can use BE paired with DTPO and Ryan’s syncing trick. I had an indexed Obsidian folder in DTPO for a while for that auto process…but eventually realized that I was fine with just the manual export with BE (which also had the advantage of the deeplink directly back to BE).
1 Like