The current official documentation is incomplete, and inaccessible for most users, however I believe it is the best zotero integration so far, if only it can eventually match the features of Bibnotes Formatter. I want to make a simple guide for users who want to quickly set up the plugin with simple use cases.
In this guide I will distill what I gathered from a day of going through the Obsidian forum thread, the github discussions and issues pages, the API guide from the documentation, and brute-force trial and error. Much of the api stuff will require knowledge of eta and javascript, which unfortunately I have limited experience with. Perhaps others can chime in and help me fill out a cheat sheet of simple templates and use cases.
I will not cover installation as that is sufficiently covered in the official documentation as well as some straightforward things such as predefined folder settings, and other misc.
Besides creating citation notes (as they call them “Literature Notes”) by importing data from zotero, AidenLX’s zotero Integration Plugin (which I will now refere to as AZP), has several features for research. Namely, two toolbars, the Fields of Literature Note Panel, and the Annotations Panel.
Starting with the Fields of Literature Note Panel, this is a panel which is linked to the active pane, and will show you the content of yaml metadata frontmatter fields (which must be specified in the plugins settings). Additionally, you may add new entries into these fields from this panel. The default fields specified are highlights, and annotations. You may add additional fields to be shown in this view by going to the plugin settings, and selecting the fields tab.
The Annotations Panel is more complex. The key purpose of this panel is to show annotations made in zotero In the side panel. There are four options here, a “collapse” (shortens the annotation cards), a “refresh” (refreshes data from zotero), “Choose Follow Mode”, and “Show Details”. The Choose Follow Mode, links the annotations panel to either: a selected literature (chosen from a list), the literature note in an active panel, or the “active literature in zotero reader” (I wasn’t able to make this one work). Lastly, there is the Show Details mode, which for a linked literature, will display the available metadata fields from zotero (this is supposed to show inside the panel, but in my experience it opened in a new Obsidian window altogether). These can also be found by opening the betterbibtex database .json file. These fieldnames are what you will use when making your templates, as will be explained below,
Currently, the templating framework is divided into several parts. Yaml metadata fields, are not incorporated into the customizable template files, and are instead edited from the Template tab in the settings under the Metadata Fields header. Here you may choose what metadata you want to be imported from zotero and into the yaml fields. You may also choose to customize the fieldname printed in the Literature Note to something other than what it is in zotero with the Specify Alias Here text-field. Fields which do not exist in zotero, will not be created in the template, and it is not possible to define custom non-zotero yaml fields I.e. fields which you may want for obsidian, such as status or priority. Not a big issue if you are a fan of dataview inline fields.
AZP uses default templates, until they are “ejected” to a defined folder. This is done in the Template tab in the settings, after which the template files may be customized. By default these zt-note.eta, zt-annot.eta, and the similarly named zt-annots.eta. The way this works is by first referring to the note template: zt-note.eta, which then references zt-annots.eta a separate template for how to create multiple annotations and references zt-annot.eta which defines the template for each individual annotation.
Below I have copied the default templates and describe the behavior in comments. Reminder, I have basically no JS experience so this is mostly on intuition.
# <%= it.title %> \\ Insert title from zotero metadata
\n \\ New line break
[zotero](<%= it.backlink %>) <%= it.fileLink %> \\ Creating a markdown link "[]()" which links to the zotero URI, and then a link to the file location
\n \\ New line break
<%~ include("annots", it.annotations) %> \\ Reference to insert "annots" template (kinda iffy here)
\\ Super unsure to the format of things here
<% for (const annotation of it) { %> \\Probably a "for all annotations in item"
<%~ include("annotation", annotation) %> \\ Make a an individual annotation item from zt-annot.eta, I don't see how it is referenceing that template file exactly
\n \\ newline break
<% } %> \\ Exit for loop?
[!note] Page <%= it.pageLabel %> \\ Makes an admontion with the page number
<%= it.imgEmbed %> \\ Embeds image if one
<%= it.text %> \\ Text selected of annotation
<% if (it.comment) { %> \\ if loop for comments on annotation
---
<%= it.comment %> \\ insert annotation comment
<% } %> \\exit if loop
I assume options to format the annotations according to content or colors is possible, but requires a deeper understanding of JS/eta than I understand. As mentioned before the official documentation has extensive API information, but I really can’t make head or tails of it. If you reading this can add some information to help with some this formatting, please reach out.
Immediately we can see how inserting information works:
<% %> Anyone familiar with the templater plugin will recognize this as representing a dynamic field, i.e. the information to be automatically pulled.
<%= it.fieldname %> appears to be how one sets in information from a field in zotero where it. stands for the “item” (so don’t change this) and fieldname is the zotero field from which the information in pulled. Just swap the fieldname with the desired zotero fields, as shown in the Show Details panel or the .json file.
<% for { %> and <% if {%> appears to serve as a dynamic function, for a for and if loop respectively. End of statement needs to be ended with a <% } %>. As seen in <% if (it.comment) { %> and <% for (const annotation of it) { %>.
<%~ %> appears to be some dynamic function, as seen in <%~ include("annotation", annotation) %>. which calls to zt-annots.eta but this is at the limit of my understanding.
<%= it.title %> paper title
<%= it.date %> year
<%= it.backlink %> Zotero URI
<%= it.fileLink %> Zotero PDF file path
<%= it.abstractNote %> insert abstract
As taken from this thread here, this uses the js/eta language to format the authors names as “first author et al. Year” when more than one author is listed.
<%= it.creators.first()?.lastName %>
<% if (it.creators.length > 1) { %> et al. <% } %>
- <%= it.date %> - <%= it.title %>
This should be enough to customize some simple templates. If you have any information that would work well here please reach out on the reddit or forum threads linking here, and I will try to incorporate it.
Additionally please check out AidenLX’s github or donate to hispatreon.
Also, perhaps check out this Obsidian forum thread here for more AZP template discussion.