An Academic Workflow: Zotero & Obsidian

Alexandra Phelan
10 min readApr 10, 2022

--

My Obsidian database in graph view, showing bidirectional links between notes, and key nodes of common tags.

Note: An updated version of this workflow is available here.

As an academic, my daily workflow involves collecting resources, reading and annotating them, creating notes, writing manuscripts, and citing references. This list doesn’t reflect the varying intensity and effort between these steps. Increasingly, “creating notes” has become the central part of my workflow: it’s where I synthesize what I’ve read, link concepts, get and develop ideas, and complete a first draft on an atomic part of a broader topic. Similarly, writing a manuscript is a huge lift, but it is easier when I have already developed these smaller, already synthesized and drafted notes (for those who know the Zettelkasten system, this will already be familiar). It’s also substantially easier for me to write in a markdown editor, than in Word, Scrivener, or Google Docs – each with their own sluggishness and distracting formatting.

Zotero: collecting resources, annotating them, citing references

For most of my academic workflow steps, Zotero performs excellently. I use my library as a database that holds nearly 15 years of my research. I add resources to my library using the browser connectors that come with Zotero or manually, meaning that all the metadata for a resource (author, title, type, journal name, date etc) is logged. Every entry in my database is also linked to a PDF of the book or article, where I can read, highlight and add notes. Then, when I write a manuscript, I can easily insert citations in whatever citation style the relevant journal or editor requires. As someone who works across the law and science disciplines, being able to switch between APA, Bluebook or Nature at the press of a button is critical. While I use Jurism — a fork of Zotero that is better designed to handle law or international sources — Zotero’s latest update to Zotero 6 prompted the recalibration of my workflow. And while I’ll continue to use Jurism for now, the workflow below should be helpful for those using Zotero 6 and Obsidian.

Obsidian: creating notes, writing manuscripts

It’s a waste of time to collect resources and do nothing with them. It’s inefficient to collect them, and then come back to a database like this just to cite a resource if you remember. For me, the synthesis of my readings and annotations into new notes that help me draft manuscripts is the most critical part of my workflow. I could use any text editor to collect these notes, or even just the note function in Zotero itself. But I want to build and connect my ideas. I’ve never worked in strict disciplinary siloes, so my writing process never has either. To really embrace this, a simple text editor, potentially with one-way links between topics, is not enough. I need bidirectional linking and delight in pluralism. That’s where Obsidian comes in. Obsidian is a markdown editor, providing a distraction free writing environment. But Obsidian provides more than just a text editor and facilitates bidirectional links to create relationships between ideas.

I. Zotero Setup

There are a range of plugins for Zotero, but I recommend installing:

  • zotfile for managing pdfs. While Zotero 6 enables annotation in the app, and storing the pdfs in Zotero storage, I use zotfile to automatically rename pdfs into a consistent format (e.g. author_date_title) and move them to a specified attachments folder not in Zotero storage. This lets me keep all of annotations saved separately to Zotero and so I can access them through my file explorer (including on my tablet for my preferred pdf reader). If you’re happy with staying within the Zotero ecosystem, this may not be necessary.
  • betterbibtex for creating citekeys. Betterbibtex does a lot, but I mainly use it to automatically create consistent pandoc citekeys (author_date, e.g. Carter_2022) that I can use when writing manuscripts in Obsidian. If you’re not planning on using Obsidian to write and cite, this may not be necessary.
My Zotero database, containing journal articles, books, chapters, reports, and primary sources like international and domestic court cases, statutes, and treaties.

II. Obsidian Setup

The second part of the workflow relies on a number of Obsidian community plugins. The Obsidian Zotero Desktop Connector is the only essential one for creating Literature Notes. However the roll-up summary page requires dataview, and exporting manuscripts written in Obsidian with citekeys to docx requires the pandoc plugin. With Obsidian (v0.14), call outs are now incorporated. I use the admonitions plugin to create customized call outs.

Literature Notes are essentially a single note for every reference, containing the full metadata, link to Zotero, and annotations and notes extracted from the PDF stored in Zotero.

Zotero Desktop Connector for Literature Notes
There are two main templates required to get the Literature Note structure — Header and Annotations. The markdown code for each is set out below. These are saved as markdown files in the vault.

  • Literature Note Header

This template –‘infoheader’– provides the formatting framework for my literature notes. I like being able to have the full citation at the top to copy-paste if needed. I also like to synthesise the core contribution the piece makes to the literature up front. The template extracts the metadata from Zotero, including using nunjucks ‘if’’ functions to populate specific resource details. After import, I manually change the first author from Author:: to FirstAuthor:: to simplify long author lists in my summary roll-up table (below).

> [!Cite]
> {{bibliography}}
>[!Synth]
>**Contribution**::
>[!md]
> {%- for creator in creators %} {%- if creator.name == null %} **{{creator.creatorType | capitalize}}**:: {{creator.lastName}}, {{creator.firstName}}{%- endif -%}<br>
> {%- if creator.name %}**{{creator.creatorType | capitalize}}**:: {{creator.name}}{%- endif -%}{%- endfor %}
> **Title**:: {{title}}
> **Year**:: {{date | format("YYYY")}}
> **Citekey**:: @{{citekey}}
> {%- if itemType %}**itemType**:: {{itemType}}{%- endif %}
> {%- if itemType == "journalArticle" %}**Journal**:: *{{publicationTitle}}* {%- endif %}
> {%- if volume %}**Volume**:: {{volume}} {%- endif %}
> {%- if issue %}**Issue**:: {{issue}} {%- endif %}
> {%- if itemType == "bookSection" %}**Book**:: {{publicationTitle}} {%- endif %}
> {%- if publisher %}**Publisher**:: {{publisher}} {%- endif %}
> {%- if place %}**Location**:: {{place}} {%- endif %}
> {%- if pages %} **Pages**:: {{pages}} {%- endif %}
> {%- if DOI %}**DOI**:: {{DOI}} {%- endif %}
> {%- if ISBN %}**ISBN**:: {{ISBN}} {%- endif %}
> [!LINK]
> {%- for attachment in attachments | filterby("path", "endswith", ".pdf") %}
> [{{attachment.title}}](file://{{attachment.path | replace(" ", "%20")}}) {%- endfor -%}.
> [!Abstract]
> {%- if abstractNote %}
> {{abstractNote}}
> {%- endif -%}
{%- set important = annotations | filterby("comment", "startswith", "important") -%}
{%- if important.length > 0 %}
> [!important] Callouts
{%- for annotation in important -%}
{%- if annotation.annotatedText %}
> - {{annotation.annotatedText | nl2br}}
{%- endif -%}
{%- if annotation.imageRelativePath %}
> - ![[{{annotation.imageRelativePath}}]]
{%- endif %}
> [page {{annotation.page}}](file://{{annotation.attachment.path | replace(" ", "%20")}})
{%- endfor -%}
{%- endif %}
{%- if annotations.length %}
## Annotations
{%- endif %}
  • Annotations

This annotation template – ‘annots’ – does a few things. Firstly, it sets out separate formatting for highlight colours. This is useful for me because I use different highlighting colours to communicate different things:
- 🟡 interesting point
- 🟢 literature to read
- 🔵 key conclusion/ratio decidendi
- 🟣 author critique of other literature
- 🔴 disagree with author
- 🟠️ highlights after first iteration

The template also extracts written annotations as notes. Here you can also set styles for underlines, strikethroughs etc, but I don’t use them so have simplified the template.

The rest of the template then allows for subsequent annotations to be added to the literature note without wiping any changes or edits made after import.

{%- macro calloutHeader(type, color) -%}
{%- if type == "highlight" -%}
<mark style="background-color: {{color}}">Highlight</mark>
{%- endif -%}
{%- if type == "text" -%}
Note
{%- endif -%}
{%- endmacro -%}
{%- set annots = annotations | filterby("date", "dateafter", lastExportDate) -%}
{%- if annots.length > 0 %}
### Exported: {{exportDate | format("YYYY-MM-DD h:mm a")}}
{% for annot in annots -%}
> {{calloutHeader(annot.type, annot.color)}}
{%- if annot.annotatedText %}
> {{annot.annotatedText | nl2br}}
{%- endif -%}
{%- if annot.imageRelativePath %}
> ![[{{annot.imageRelativePath}}]]
{%- endif %}
> [page {{annot.page}}](file://{{annot.attachment.path | replace(" ", "%20")}}) [[{{annot.date | format("YYYY-MM-DD#h:mm a")}}]]
{%- if annot.comment %}
> - {{annot.comment | nl2br}}
{% endif %}
{% endfor -%}
{% endif -%}

III. Creating Literature Notes

Once the Header and Annotations files are setup, activate the Obsidian command picker (cmd-p on mac) and select “Zotero Desktop Connector: Create Literature Note”. I have set this to a hotkey to immediately launch.

The Zotero prompt should appear, and you can type in your reference for which you’re creating a Literature Note.

Once selected, ZDC will run, and output in one Literature Note the Header and Annotations:

The first two references have been manually edited as part of synthesis process.

You can then edit the document, and edits will be preserved. If you subsequently add more notes and annotations in the relevant PDF, they will be added in separate entries when you re-run “Zotero Desktop Connector: Create Literature Note”. If you move the Literature Note from the output folder, this will not update the moved file but will instead create a new note in the original output folder. I recommend therefore keeping one Literature Notes output folder and not moving your files.

Summary Roll-Up of Literature Notes

In a new Obsidian note, dataview can be used to create a roll-up of all literature notes:

```dataview
table
title as Title,
FirstAuthor as "First Author",
Year as Year,
itemType as Item,
Citekey as Citekey,
Contribution as Contribution
FROM "[insert Literature Notes folder here]"
```

which results in:

IV. Writing manuscripts

Writing in Obsidian is essentially the same in any other text editor, except formatting is done using markdown:

Zotero Desktop Connector can be used to add in citations. First, you need to set your preferred citation styles. Ensure that you have the selected style installed (CSL) in your Zotero (Preferences > Cite > Styles). This will insert the completed citation in the preferred format.

Alternatively, you can also setup Pandoc citations that allows you to easily change formats as required (for example, if submitting to different journals).

Adding citations

Use the Obsidian command prompt to navigate to the citation style you want to insert a citation for. You can setup hotkeys to immediately go to your preferred style.

You can then select the relevant citation in Zotero…

and the selected cite is inserted into the document. Here, I have used a pandoc citation:

Converting from markdown to docx & process citations

Setting pandoc to read your Zotero library
Once citations are added, you can process them using the pandoc plugin. The first step is to export your Zotero library as a .bib file, and then point the pandoc plugin to it. You can do this using YAML frontmatter:

---
bibliography: ~/yourpath/My library.bib
---

or set it permanently in the pandoc plugin by adding to the Extra Pandoc Arguments box:

--metadata bibliography=~/yourpath/My Library.bib

Setting pandoc to process citation in preferred style

The default pandoc citation is Chicago (author date).

If you want to change the citation style or which zotero library you’re extra, you can set the CSL in the YAML metadata or in the pandoc plugin settings:

---
csl: ~/yourpath/style.csl
---

or set it permanently in the pandoc plugin settings by adding to the Extra Pandoc Arguments box:

--metadata csl=~/yourpath/style.csl

Exporting to docx

Simply open the command palette and select pandoc plugin: export as word document (docx). It will export to the same folder as the md file, or to a specified export folder provided in the obsidian pandoc plugin settings.

Alternatively, if you’re on a mac, you can use Terminal to do all of the above. Installation instructions here.

pandoc "path/to/input.md" -o "path/to/output.docx" --citeproc --bibliography "path/to/library.bib" --csl "path/to/citation_style.csl"

Going forward

Once you are familiar with the processes and the setup, the workflow runs incredibly smoothly. This is a steepish learning curve if you have limited programming experience or comfort, but this is a fairly user-interface-driven friendly approach to developing a full academic research and citation workflow.

Thanks to the Obsidian Discord, especially Mathew Meyers, Chris Grieser, Eleanor Konik, Leah Ferguson.

--

--