Zotero best practices

Thank you very much for your quick reply and for your availability.
I have no Discord Account. Will proceed to create one and then contact you there in the near future.

Thank you once again

Have a great day

thanks, i just found out about this feature in Bryan Jenks’s recent video and was looking for to learn how he did separated notes based on annotation color.
Can you please explain it in more details, I have changed value of .colorAnnotaions to true, but i can’t understand what exactly should i do after that.

@PedroSilva In Zotfile’s documentation it mentions which option to use to format the colours, i.e. you need to add the wildcards to formatAnnotationHighlight:

For example, change formatAnnotationHighlight to <p style="background-color:%(color);">"%(content)" (%(cite))</p>. The wildcard %(color) is replaced by the annotation color (you can also use %(color_category) for the color category—reddish is red etc). This styling has the same effect but looks a little better: <p><span style="background-color:%(color);">"%(content)"</span> (%(cite))</p> (b) To create separate notes for color categories: The hidden option pdfExtraction.colorNotes allows you to create a separate note for each color category (yellow, red, green etc annotations).

For that to work you need extensions.zotfile.pdfExtraction.colorNotes set to false and extensions.zotfile.pdfExtraction.colorAnnotations set to true. If you have them the other way around, the wildcards will sort of work (you can use them to color things, but it doesn’t get the color name properly). See here, I added the wildcards %(color) and %(color_category) respectively at the top:


@Archie after setting the colorAnnotations to true, you should right click the PDF, then select Manage attachments > Extract annotations. I don’t think you need anything else unless you want to customize how the annotations look.


thanks, yes that is what is needed, other options are only for changing the format. it is really a cool feature, i though i am forced to learn regex to automate such a process

@Archie what do you mean?

I think you should set both values of colored annotation and colored notes to true for it to work.

Sorry I am still not quite understanding.
I want to have one annotation with no colour separation and each note with the colour specified inside the annotation. Should I not want
extensions.zotfile.pdfExtraction.colorNotes true?

I also tried and replaced color with colour category like so:
<p><span style="background-color:%(color_category);">"%(content)"</span> (%(cite))</p>

Unfortunately it ends up just showing the colour code instead of saying red:…, blue:…
Nevertheless, I have been working with your workflow without any colour coding and it is such a breeze. Thank you very much

By the way, have you considered somehow making your plugin work with the new built in pdf preview in Zotero?
Although the preview does not save the annotations on the PDF itself maybe it is better to sync with the future mobile app?
It seems promising, what is your opinion?

@PedroSilva yes, that’s what the docs above say. For example, this is what I have on mine:

Indeed! That’s what the demo showed, and afaik it is not possible to use both simultaneously. Either you split by colour or you get the tags. I don’t personally use this, but maybe you can try what Archie mentioned above.

Eventually, yes. I can’t update to the beta at the moment (I’ll wait until it’s a bit more stable, especially for Linux). I’ve added a discussion for this in the GitHub repo: New Native Annotations in Zotero (Currently on Beta) · argenos/zotero-mdnotes · Discussion #77 · GitHub


The new beta versions of Zotero include a built-in PDF viewer that allows for comprehensive notetaking, tagging, export annotations (not yet customizable/formattable like with Zotfile) etc…

The dev seems very open and responsive to feedback, so its worth checking it out and giving ideas! Markdown stuff seems to not be a priority due to technical difficulties, but perhaps if enough people are politely persistent, he can make it happen! But, there’s no reason you can’t use mdnotes with the notes and annotations that are created with this viewer.

Note that he mentioned somewhere that installing/using the beta will create major changes in your database, so its worth backing it up first.

This should solve a lot of my issues - I’ll likely just import all my PDFs into Zotero, work on it all from there and then import to Obsidian when ready, pasting links in each app for the other.

pdf reader preview [Zotero Documentation]

1 Like

Just a few comments: This does not work with mdnotes directly right now. I will eventually add support.

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.

Please back up your database before testing the beta: zotero_data [Zotero Documentation]
The beta makes changes to the database schema, so downgrading might not be fully possible.


You can “Add Note Item from Annotations” in the right panel where it creates a note - as Zotfile does - which mdnotes could then convert. The problem is that the notes don’t have any formatting (yet?) - so no colors or hyperlinks are created.

However, it does create a citation with page number for each annotation, so I wonder if mdnotes could somehow create hyperlinks by finding the citation and appending " “zotero://…” to it?

The database-based annotations really does offer a lot of benefits over standard embedded highlights - you can add zotero tags to any annotation for searching, cross-referencing etc…

1 Like

The zotero:// links come from Zotfile’s PDF extraction and mdnotes just translates the HTML notes into Markdown. I’m afraid that for us to get those links, Zotero has to add them to their annotations when they are translated as notes, or they should be available as part of the annotation data structure, so they can be built on export when mdnotes supports this.

1 Like

This link is not working. I’m using this alternative which is quite easy.

1 Like

Thank you pointing it out, I have updated the link.

hey, and thank you for your effort
I am using your translator but I am getting the output in this format when I drag and drop:
i can’t figure out why, I looked into the script and the format there seams right. I don’t know what is wrong , may be there is an overlap with BibTex or something. Does anyone have the same problem.

In terms of getting the color names to show up in the exported annotation (ala @PedroSilva ) , you can modify the categories in extensions.zotfile.pdfExtraction.colorCategories and remove the hex code and replace it with the color name. Then when using @color_categories in extensions.zotfile.pdfExtraction.formatAnnotationHighlight you will get the name instead of the hex code

{“Black”: “#000000”, “White”: “#FFFFFF”, “Gray”: “#808080”, “Red”: “#FF0000”, “Orange”: “#FFA500”, “Yellow”: “#FFFF00”, “Green”: “#00FF00”, “Cyan”: “#00FFFF”, “Blue”: “#0000FF”, “Magenta”: “#FF00FF”}

{“Black”: “Black”, “White”: “White”, “Gray”: “Gray”, “Red”: “Red”, “Orange”: “Orange”, “Yellow”: “Yellow”, “Green”: “Green”, “Cyan”: “Cyan”, “Blue”: “Blue”, “Magenta”: “Magenta”}

If you want the highlighted color to show up in Obsidian as well you could use the 8 x 8 Highlight Colors CSS from @Steve_yang.

{“Black”: “#h/black”, “White”: “#h/white”, “Gray”: “#h/gray”, “Red”: “#h/red”, “Orange”: “#h/orange”, “Yellow”: “#h/yellow”, “Green”: “#h/green”, “Cyan”: “#h/cyan”, “Blue”: “#h/blue”, “Magenta”: “#h/magenta”}

Then your extensions.zotfile.pdfExtraction.formatAnnotationHighlight value would need to include the highlighting syntax that Obsidian uses:

<p>%(color_category)==<span style=“background-color:%(color);”>"%(content)"</span>== (%(cite))</p>



I made color meaningful

{“Purple”: "[[Integration]]: ", “Red”: "[[Important]]: ", “Orange”: "[[Example]]: ", “Yellow”: "[[CentralIdea]]: ", “Green”: "[[Example]]: ", “Cyan”: "[[Citation]]: ", “Magenta”: "[[Figure]]: ", “Grey”: “[[Other]]”}


{“Black”: “”, “White”: “”, “Gray”: “Argument”, “Red”: “#Disagreement:”, “Orange”: “#Agreement”, “Yellow”: “#CentralIdea”, “Green”: “Example”, “Cyan”: “#Data”, “Blue”: “#Theory:”, “Magenta”: “#Citations”}

together with some tweaks I will get html code with color values in my output file which will display the color in view mode

#CentralIdea  <span style="background-color: rgba(153,255,153,.25);"><strong>(Green)</strong> - From fidgeting to expeditions, natural body movements manifest over a very broad range of spatiotemporal scales. The complexity of such movements is often organized with fractal structure, scale-free fluctuations spanning multiple spatiotemporal orders of magnitude (1-4). Such behavioral complexity may be beneficial for foraging (3-6), visual search (4), decision making based on priority (7, 8), flexible switching of behavior (9), and perhaps more. Similarly, fluctuations of ongoing neural activity in cerebral cortex can exhibit fractal, scale-free fluctuations like the spatiotemporal cascades sometimes referred to as 'neuronal avalanches' (10-18) and long-range temporal correlations (19-21).</span> ([Jones et al 2021:2](zotero://open-pdf/library/items/JAAPML5T?page=2))

Thanks for this! As @icebear and @yongqi have asked before, is there anyway to make a shortcut for this? So instead of drag and drop, I can copy-paste with a keyboard shortcut

Edit: My bad, I realize this can be achieved with cmd-shift-c, the default Quick Copy shortcut.
This will be really useful for quickly adding a citation when I’m not looking to create a bibliography


Just a nice simple one - is it possible to modify this translator so that it links to the URL (web version of Zotero) rather than the desktop?
The resulting output would be like the “Item URI” translator.

Thank you!!


1 Like

This is so far the best review of some useful setups about Zotfile. I have one issue that remained, which is about extracting colored annotations. I don’t really understand how to use %(color_category) instead of %(color).

I did see on Zotfile’s website about the explanation: The wildcard %(color) is replaced by the annotation color (you can also use %(color_category) for the color category—reddish is red etc). So when I use%(color), I did see text highlighted with the specified color under extensions.zotfile.pdfExtraction.colorCategories. But how to set %(color_category). I expect to see for example, (Yellow-Conclusion).

1 Like