With the help of @SkepticMystic, I have put together a plugin called “BibNotes Formatter” which captures my workflow for getting pdf annotations from Zotero into Obsidian (GitHub - stefanopagliari/bibnotes). This plugin generates literaure notes from the source stored in your Zotero library, including both the metadata and the annotations that are stored within Zotero (extracted using the native PDF Reader or the Zotfile plugin). The settings of the plugin provide different tools to customize the format of the literature notes, as well as to perform different transformations to the text of the annotations.
The plugin combines some of the elements that are familiar to those using zotfiles/mdnotes to get your annotations from Zotero into Obsidian with a few significant differences:
- The plugin reads a json file exported from Zotero (using the Better BibTex plugin) which is updated automatically. As a result, it is possible to automatically keep in synch the entire set of notes exported from Zotero using the “Update Library” command (see GitHub - stefanopagliari/bibnotes)
- When updating an existing literature note, the plugin does not over-write the changes made to the note previously (e.g. reference blocks, comments added manually on Obsidian). This allows you to keep the literature notes on Obsidian updated when the data is changed in Zotero without the risk of losing the manual edits
- I have added in the settings a few options to format the highlights. These includes basic formatting (e.g. bold, bullet points, italic, quotation marks), but also more complicated custom transformations (GitHub - stefanopagliari/bibnotes) such as turning the highlights into heading and tasks, merge an highlight with the previous one (to combine a paragraphs running across two pages), copying the comment before the related highlight, adding a word to the list of keywords. I would be happy to introduce additional transformations if there is demand.
- The plugin works with notes extracted both from the Zotero native pdf reader and via Zotfile.
This is the very first version of the very first adventure in JS/plugin-building. If anybody wants to give it a try and give any feedback on bugs to fix or possible improvement that would be much appreciated.
Importing your Zotero Library into Obsidian
In order to import your references and notes from Zotero, you need to export your library as a “BetterBibTex JSON” format and save this file inside your vualt. To do to follow these steps:
- install within Zotero the plugin “Better BibTex for Zotero”. For more information on how to install the plugin see the instructions on the website of the plugin.
- in the main menu of Zotero go to File > Export Library (to export the entire library). It is also possible to to export a specific collection or group of references by selecting these, right-click, and then selecting “export collection” (in the case of a folder) or “export items” (in the case of a collection of references.
- select the export format “BetterBibTex Json”.
- select “Export Notes” if you would like to import into Obsidian the annotation.
- (Optional) select “Keep updated” to automatically update the exported library once an entry is added/deleted/amended
- save the BetterBibTex JSON file in a folder within your Obsidian Vault
- in the plugin settings within Obsidian add the relative path within your vault of the library to be imported, as well as the relative path within your vault of the folder where you would like the literature notes to be stored.
Commands
The plugin introduces two commands into Obsidian:
- Create/Update Literature Note: when you select this command you will be prompted to chose one of references from the library you have imported. If the reference has not been imported yet in the specified folder, a new note will be generated. If a note already exists, its content will be updated without over-writing the existing annotation (e.g. comments added manually from within Obsidian and block-references will not be over-written). The first option (“Entire Library”) can be selected to create/update all the notes from the imported library.
- Update Library: when you select this command, the plugin will generate/update all the notes that have been modified from Zotero since the last time the same command was selected. If this is the first time that you select this command, then the plugin will create/update literature notes for all the entries in the imported bibliography.
Create Literature Notes
By default the plugin will export both the metadata and the notes stored in Zotero for the selected reference. Both can be deselected in the plugin settings. The main configurations related to the format of the notes are the following:
- Export Path: in the plugin settings, add the relative folder within your Obsidian vault where the literature notes will be stored. In the field is left empty, the notes will be exported in the main folder.
-
Note Title: In the plugin setting you can specify the format of the note title. Possible values include:
- {{citeKey}},
- {{title}},
- {{author}},
- {{year}}
- Template: It is possible to select among two existing templates (one presenting the metadata as a simple list and the other wrapping the information into boxes using the Admonition plugin) or to or provide a custom template (see below).
-
Fields: It is possible to include in your custom template all the fields found in the Better Bibtex json file, as well as additional ones created by the plugin. These include:
- {{title}}
- {{citekey}}
- {{itemType}}
- {{author}}
- {{editor}}
- {{translator}}
- {{publisher}}
- {{place}}
- {{series}}
- {{seriesNumber}}
- {{publicationTitle}}
- {{volume}}
- {{issue}}
- {{pages}}
- {{year}}
- {{dateAdded}}
- {{dateModified}}
- {{DOI}}
- {{ISBN}}
- {{ISSN}}
- {{abstractNote}}
- {{url}}
- {{uri}}: link to the entry on the Zotero website
- {{eprint}}
- {{file}}: local path of the file attached to the entry
- {{localLibrary}}: link to the entry on the Zotero app
- {{keywords}}: tags associated with the entry
- {{collections}}: collections/folders where the entry is located
- {{collectionsParent}}: collections/folders where the entry is located, plus the parent folders to these
- It is also possible to wrap the placeholders into [[ ]] in order to create notes or to preface them with :: in order to create Dataview fields.
- Missing Fields: Fields that are present in the template but missing in the entry are deleted by default. This can be changed in the settings.
Basic Formatting
In the settings of the plugin, it is possible to select the formatting of the highlights and comments extracted from the text. These include:
- Double Space
- Italic
- Bold
- Quotation Marks
- Highlight
- Bullet Points
- Blockquote
- Custom text before or after all highlights
- Custom text before or after all comments
Additional Highlight Formatting
It is possible to perform additional transformations to designated highlighted sentences. The transformations currently included in the plugin are:
- Heading: Turn highlighted text into a heading (Level 1 to 6).
- MergeAbove: Append highlight to the previous one (e.g. to merge paragraph across two pages).
- Preprend Comment: Place the text of the comment at the beginning of the highlight (rather than at the end as by default).
- Keyword: Add the highlighted text to the list of keywords listed under the ({{keywords}}) placeholder in the template.
- Todo: Transform the highlight or comments into a task ("- [ ]").
- Custom Text: Add custom text before or after a specific highlight
Keywords
Transformations can be triggered by adding a dedicated “keyword” at the beginning of the comment to the specific highlight. This can be a single character (e.g. #) or a single word (e.g. todo). When this character/word is found at the beginning of a comment, the text of the comment or the highlighted text will be reformatted. The keywords can be defined in the settings of the plugin
Highlight Colour
In addition to using dedicated keywords at the beginning of a comment, it is possible to apply specific styling or transformations to highlights based on the colour of the highlight. The plugin recognize the highlight colour extracted by:
- Zotero native reader (yellow, red, green, blue, purple)
- Zotfile plugin (black, white, gray, red,orange, yellow, green, cyan, blue, magenta). In order to export the highlight colour you will need to activate this function by going to the main menu of Zoter and selecting Preferences → Advanced → Config Editor. Search for “extensions.zotfile.pdfExtraction.colorAnnotations” and turn the value to “true”. It is also important that the value “extensions.zotfile.pdfExtraction.colorCategories” is restored to the default value.
