New Native Annotations in Zotero (Currently on Beta)

[argenos]

Please use this thread to discuss ideas around the new annotation features in the Zotero beta: Native PDF annotations.

Quoting the reply I gave to an answer in another thread about supporting this:

I do have plans to support this once it's out of the beta. For now, you can try the following (taken from [here]):(https://www.zotero.org/support/pdf_reader_preview):

Annotations are stored in the Zotero database, not in the PDF file, which allows for much more advanced functionality as well as fast syncing. The File menu contains a new option to export PDFs, which will convert any Zotero annotations into standard annotations in the exported file. (An upcoming version will let you omit annotations, but in the meantime you can drag files to your filesystem to copy just the file.) Similarly, when exporting metadata from your library, there's a new “Include Annotations” option under “Export Files”. We plan to support other ways to export annotations in future updates. Your annotations will never be locked in Zotero.

The biggest problem with the changes will be whether the way to access these new annotations is documented somewhere in the API (not yet), or if I have to dig through their code to get them out. It might be that later on they support the ability to export them themselves.

[argenos]

Because the annotations are just an array of unformatted (non-html) notes with some fields, a few things need to be defined:

Files

Should annotations be exported in a single file or multiple ones?

• if each annotation should get its own file, what is the naming convention?
• Split on different files based on colour?
• Splitting annotations from highlights?

Formatting

• Custom formatting for different "types" of highlights or annotations? If you colour-code things, this might be interesting in combination with the grouping/splitting options above.

[tallguyjenks]

Notes from exploration of the annotations/desktop/mobile apps:

looks like annotations made with the prior version (a yellow highlight/note) when viewed in mobile lets me see it and read the annotation note but i cannot remove/edit the annotation from the pdf.

the desktop recognizes other color annotations (orange) but when accessed on mobile i cannot see them at all after a sync

in desktop in the right hand side if you click "new note" it gives option to select "from annotations" and then it basically enables the entire zotfile/mdnotes workflow. The note is made from the annotations and i can convert to markdown successfully.

so it looks like:

• classic annotations can be made and recognized
  • viewable but not edit-able in mobile or desktop
• non-standard colors (orange in highlights app) is shown and recognized and extractable in the desktop app
  • not even viewable in the mobile app
• All annotations including classic and non standard color can be extracted to notes and then exported to markdown successfully, content and annotations
  so this actually doesnt break the workflow for me anymore. Thanks @nixsee ! now i can stay in the new verison :slight_smile:

[nixsee]

Adding onto what @tallguyjenks said, and what I've said in the obsidian discord:

• At the moment we are forced to either choose and stick with the beta or the normal version because saving notes to the pdfs in the beta ends up creating duplicate notes in the PDF. Given that the beta is the future of Zotero, it would make sense to make any workflow compatible with the direction in which it is going. It also just seems like an ultimately superior workflow anyway, with the ability to add searchable tags to any annotation, and much more. You can also export/hardcode annotations into PDFs for sharing/use in a standard PDF workflow.
• There are various bugs and shortcomings in the beta - e.g. lack of highlight styles, highlight colors not being properly exported - but the devs seem receptive to bug reports/basic feature request so I would imagine it will all work out favorably in due time.
• At the moment, the beta does not allow for the use of zotero:// links to be appended to extracted annotations, as is done with Zotfile. This seems like the biggest shortcoming to a Zotero Beta/mdnotes/obsidian workflow. Hopefully you are able to find the annotations' location reference somewhere in the API/database.
• It would be great to have templates/placeholders (as is the case currently for zotfile/mdnotes) for editing how the annotations are converted - allowing for us to choose whether/how colors are used, splitting or combining notes, spacing between notes etc...

[argenos]

It also just seems like an ultimately superior workflow anyway, with the ability to add searchable tags to any annotation, and much more.

I don't fully agree. We know that different strokes for different people. I took a little time to set up a profile to test with the beta over the weekend, and the beta simply has too many limitations currently. I'll add my summarized comments from discord and other issues below. As you say, this will likely be addressed later, and I remain to be convinced that the annotation lock-in is worth it.

The main limitations I found:

• Limited amount of colours (5 max, predefined)
• It only does highlights (no underlines, which are essential to me, others might use other PDF viewers that support other types of annotations too).
• The extracted annotations when saved as a note don't have the zotero:// link to the page. They have added something similar that works within Zotero, but that makes it useless right now if you want to export/copy-paste that note somewhere else.

The advantages:

• image-style clipping - images stored in the DB might not be easy to get out (see Support the export of images to markdown? #62)
• individual tagging of the annotations, I however couldn't get Zotero to show my annotations by filtering tags
• annotation searching - this was already possible IMO
• others have mentioned categorization, but I found no way to do that

Other things missing that Zotfile offers (Most likely some of those gaps can be covered by mdnotes possibly during export):

• Grouping annotations by colour
• Custom formatting for the note title, highlights and annotations (particularly relevant if you want to make distinctions between the latter two)
• Wildcards
  • Using the colour and colour category wildcards to format the note's contents
  • Formatting the date as you see fit

I understand the appeal for some to have everything under a single app (Zotero), but the viewing/annotating experience is still very limited and any PDF viewer can do a lot more. I assume this will get better with time, but for now I'm not convinced.

[nixsee]

Another thought. Something to give some serious consideration to, especially in a Zotero/Obsidian workflow, is where attachments are stored.

I think people would typically like to have only one copy of a file, so if the plugin could create links in each application that point to the other, that would be fantastic.

Zotero seems relatively agnostic about whether a file is stored in the Zotero data directory or is externally linked. Meanwhile, Obsidian seems to prefer to have files in its attachments folder - previews of embeds only work if that is the case.

On the other hand, Obsidian, seems to have a very non-optimal way of handling obsidian:// links - if a file is renamed, external links will break, whereas Zotero should be able to track any changes because zotero:// links point to a static database index code rather than a filename. e.g. if ABC changes to DEF, a link of obsidian://ABC pasted in Zotero (or elsewhere) breaks, whereas zotero://1234567 will appropriately update to point to DEF.

So, it seems like it's a choice between link integrity and use of embedded previews. Perhaps there's a way to allow users to choose one or the other, but if there has to be a singular choice, I think its worth giving up Obsidian pdf preview and using zotero:// links to whereber the file will be store instead of attaching within the Obsidian vault.

It seems like the mdnotes output could just create a customizable tempalte like
{title}
{zotero://link}
{content}

Perhaps the output could be automatically put into the Obsidian Vault (which might already be the case?), so that the mdnotes output is automatically "imported" into Obsidian, but the PDF remains wherever zotero thinks it is (which could be changed later manually or automatically with Zotfile).

And added bonus would be if the Zotero Item Metadata could be automatically updated to include something like: zotero://vault-path/filename. Again, this would break on any filename changes, but is better than nothing, I suppose.

An obsidian feature request to incorporate the use of UUIDs is here: https://forum.obsidian.md/t/uuid-for-note-links-in-url-scheme/14617.

[argenos]

I think people would typically like to have only one copy of a file, so if the plugin could create links in each application that point to the other, that would be fantastic.

Do you mean PDF files? It hasn't really been in my plans to support anything new in this regard. I think zotero:// links work well enough for cross-application linking (even with linked attachments, which means your PDF could live inside your vault). You have the choice to use file:// links too if you so wish, but it is known that these are fragile and will break if you move or rename your PDFs.

Regarding the exported markdown files, I can't track any renaming happening after the file is created. The obsidian:// links assume you won't rename the exported files and the naming convention+workflow for the export is in my opinion the best we can do.

[nixsee]

I think we're on the same page. It is best to use zotero:// links within Obsidian, rather than embed/import files into the obsidian vault, because it won't track any changes outside of the program.

[brimwats1]

Heads up that Zotero just announced PDF.js and image extraction support: https://www.zotero.org/support/pdf_reader_preview

[nixsee]

@brimwats That's what's under discussion here already

[seb-mm]

How I would style my template

> the highlighted text would go here
<cite>("Book title", 2020, p. 6)</cite> #zotero/yellow
-  Here comes my comment. If I only highlighted but didn't comment, then the bullet point shouldn't appear

---

I'm not sure whether a separator is a good idea. For lots of entries it would be annoying, I think. But an option would be great.

---

options

1. There should be styling options/different templates for the output based on the annotationType:

• highlight
• note
• are there other types?

2. Options based on the colour of the highlights:

• they are stored as hex values in annotationColor
• grouping of the same colour in the order in which they are in the json
  • either in one file
  • or in split files
• or no grouping based on colour but in the order as they appear in the json only
• same as the bullet point above, but in addition a tag #red, #yellow or perhaps nested #zotero/red, #zotero/yellow which is added after the source (or somewhere else)
  • it would be good if the tags could be specified depending on their colour instead of having fixed tags for the colours
• the option to define names based on the hex colour once not only the basic colours are available

3. Options for styling:

• the annotationText: this is the highlighted text, so perhaps an option to prepend > to get a markdown block quote
• the annotationComment: an option to prepend - to get a bullet point or whatever the user wishes, so the option to append and prepend something
  • when there's no comment, there shouldn't be an empty bullet point
• an optional user-configurable separator for the annotations/notes

template placeholders

It might be easier to have a template note with placeholders instead of configuring it over a GUI/over the config.

> {{annotationText}}
<cite>{{citation}}</cite> #zotero/{{annotationColor}}
- {{annotationComment}}

The citation is not in the json.

[adibMosharrof]

Could you please share what I have to do to customize the output template of a note.

[lterfloth]

Just to add one thing, it would also be very helpful to be able to change the default title of the notes.