Streamline Your Literature Reviews: A Powerful Reading Workflow for Academics Using Obsidian and Zotero

How to set up an automated literature review workflow in Obsidian, powered by the Kanban plugin

by @FeralFlora

Table of Contents:

Why use this script?

My main motivation for developing this was to avoid having to go to Zotero when deciding what to read next.

I still use Zotero tags to indicate reading status, but rather than filtering by tags in Zotero or using Advanced searches, this workflow lets me see all that in a Kanban in Obsidian🎉

This way, it's much easier to get an overview of my reading 📚

Here's how it goes:

1. Use Zotero tags to specify the reading status of items:
   1. Here's what I used, for reference (in the order of my reading workflow):
      📚, 🔵, 📗, 📓, 📑, 🔁
   2. These correspond to the following reading stages:
      Reading stack, Currently reading, Read, Imported (to Obsidian), Incorporated, To re-import (if I have made additional annotations)
2. Organize, plan and update the reading list using a Kanban board, where each reading stage is a list in the kanban
3. Import read and annotated papers as literature notes using Zotero Integration
   1. Trigger imports simply by clicking on the file link in the Kanban 🔥
4. Sync and update your reading list based on the tags in Zotero using the kanban-maker-quickadd.js script.

How does it work?

1. The Kanban maker script collects the following information from the Kanban board, which is just a markdown file with headings for each list of citekeys:
   1. The properties / YAML
   2. Any citekeys, grouped by Kanban list, which is just a heading in the underlying markdown
   3. The Kanban settings at the bottom of the file
2. Kanban maker then reads the JSON data from Zotero
   1. It stores all items with the target tags, under sets which correspond to the Kanban lists in your board
3. Most importantly, Kanban maker merges these reading lists from Obsidian and Zotero, while handling conflicts in reading status according to the workflow you've specified.
   1. The merging assumes a linear workflow similar (but not necessarily identical) to this:
      Reading stack ▶ Currently reading ▶ Ready to import ▶ Imported ▶ To re-import and so on.
      1. This way, the workflow represents a hierarchy of which reading statuses should overrule which. Further explanation follows in the setup guide below.
4. Lastly, Kanban Maker writes everything it collected, including the Properties, merged and updated sets of citekeys for each reading stage / kanban list, and the kanban settings back to the kanban file.
   1. It formats the citekeys like so:
      [[importFolderPath/@citekey|APA formatted alias]].
   2. Using the script settings, you can specify additional info to import from Zotero (see the section on QuickAdd setup)

Setup

Plugins required & recommended

First steps

1. Install the required plugins (see above), and optionally also the recommended ones
2. Make a Kanban board with a list for each stage of your reading workflow
   1. 
      1. Each list should be matched to a corresponding tag in Zotero!
         1. The tag can be anything, so long as it is useful to you!
         2. Here's an example: the tag #read and list heading Read, or #to-read and Reading stack
            1. They match conceptually, not necessarily literally.
3. Export your Zotero collection in the BetterBibtex JSON format
   1. Enable the "Keep updated" option when exporting to set up an automatic export
4. Download kanban-maker-quickadd.js from here, and save it to a folder in your Obsidian vault (like "Scripts" or something similar).
   1. Right click Raw and press Save link as:
   2. If you already implemented an earlier version of this workflow, you might be surprised to learn that you shouldn't edit anything in the script itself now!

Most of the setup will be done in QuickAdd from now on, see you below 👇

QuickAdd setup

1. Open QuickAdd's settings and press:

2. Name the macro and press Add macro

3. Press Configure

If you want the script to run on startup of Obsidian, enable Run on plugin load here 👆This way, the Kanban will always be up to date when you start Obsidian.

4. Under User Scripts, search for "kanban-maker-quickadd", select it and press Add

5. Now that the user script is added to the macro, we need to configure the script. Press the ⚙️ icon next to the user script to open the scripts settings:

6. This is where the magic happens ✨ Specify your paths and settings:

• The image above 👆 illustrates how the settings affect the kanban cards and lists (open it in a new tab to see it bigger).
• The emoji toggle controls whether your List headings have their associated tag prepended. This only makes sense if the tags are emojis.
• You can import collections, or not. If you do, they will be formatted as tags with spaces replaced by -. Only bottom level collections (collections without sub-collections) are imported along with their parent collection, if present. This is meant to prevent clutter in the case of deep nesting. The order is #ParentCollection #ChildCollection.
• The "favorite" tag setting 1) imports the tag you specify here and 2) places it at the start of the line in the card. This ensures that it is consistently placed as the first of all the tags.
• Each item has a backlink to select the item in Zotero. You can set the link text to whatever you like. The default is 📝to save space, but you could replace it with something like "Open in Zotero". These links also work with iOS Zotero app, and likely also with the upcoming Android app.

With the above explanation in mind, remember that this presumes a linear hierarchy where you read and process literature in an orderly fashion, like for example:

Reading stack ➡️ Currently reading ➡️ Read ➡️ Imported ➡️ Incorporated ➡️ To-reimport.

So the caveat is, no unilateral backtracking. The script won't allow it.

So, for example, if you move an item from the Read list to Currently reading, but Zotero has the item tagged #read, the item will be moved back to Read when you run the script. Hopefully, this limitation will be taken care of when I get two-way syncing back to Zotero implemented 🤞

7. Last but not least ❗ In order to run the script, we need to set the previously created macro as a QuickAdd choice, so that it becomes available in the Command palette:
   1. In QuickAdd's main setting page, find the Add Choice button,
   2. First, name the choice
      1. this name is what you will see in the command palette and the Run Quickadd dropdown
   3. and set the choice type to Macro, then press Add Choice:
   4. Now, you should see the newly created choice just above Add choice ☝️ To make the choice functional, you need to specify which macro you want this choice to trigger:
      1. Press the ⚙️next to the choice
      2. Select the macro you created earlier. Now, the choice is ready!
      3. If you want this choice to be a distinct command that doesn't require you to use the Run QuickAdd command first, then press the little ⚡ icon next to the choice so it turns yellow.

That's it! Now you can update your kanban reading list from the command palette ctrl/cmd + P using one of the following commands:

• Update kanban (depending on what you named your choice)
• Run Quickadd ▶️ Update Kanban.

In addition, if you enabled Run on plugin load in step 3, your kanban will always be up to date with your Zotero changes when you open Obsidian.

To get the most out of your Kanban, continue reading below, where I cover Kanban settings, one-click Zotero integration imports and Zotero addon settings 👇

Recommended Kanban board settings

With the Kanban open, there is a ⚙️ in the upper right corner of the tab bar which opens the board's settings:

I recommend using the following settings:

• Hide tags in card titles: Enabled
  • This is to prevent the tags from being displayed twice.
• Color code your "favorite" tag and perhaps also some categorical subject tags or category tags:

• Specify properties you want to display below the imported Zotero items:

This is how the Properties look in the Imported list with the settings above:

CSS Snippet for Colored lists

If you like the colored lists you see in my screenshots, grab the kanban.css snippet in the Gist. Direct link here: kanban.css

To use it, save the file to your Vault ▶️ .obsidian ▶️ snippets folder, and activated it under Appearance in Obsidian's settings.

I adapted a snippet made by imstevenxyz (Steven I.) · GitHub, which I found in this this comment on the Kanban plugin's GitHub repo.

One-click literature note imports and updates

1. Copy this snippet (the copy button is non-functional - select the code manually):

2. Create a new template in your template folder (make one if you need to), and paste the snippet you copied on the first line of the template.
   1. Give the snippet an informative name like runImport.md
   2. Replace 'Import name' in the snippet with the actual name of your import, which you've specified in Zotero Integration's settings (see screenshot)

3. In Templater's settings, Enable Folder templates
4. Set the newly created template as a folder template for your Zotero import folder
   1. This triggers a Zotero Integration import on any new file created in the folder. 🥳
   2. The filename has to correspond to the citekey of the item for this to work. Kanban Maker takes care of this when importing items from your Zotero bibliography, but when you add stuff to the Kanban manually, use the citekey of the item.

Zotero setup

Colored tags

For ease of tagging, I recommend assigning a color to all your reading workflow tags, and other tags you use commonly. You can assign colors to nine tags at most.

If your tags are text, this adds a color indicator next to each item with the tag in the item. If the tag is an emoji, the emoji is displayed instead of the color indicator:

Here's how to assign colors to tags:

1. Right click the tag in the tag pane, and press Assign Colour

2. Choose a color and position

• The position determines two things:
  • The literal position of the tag in the tag panel
  • The keyboard key you can press to apply the tag

The latter point is probably the most useful aspect of assigning colors to tags. For example, pressing the 1 key on your keyboard will add the tag assigned to position 1, and so on.

MarkDBConnect

To automate tagging of Zotero items with literature notes in Obsidian, install MarkDBConnect.
Then, go to Tools ▶️ MarkDBConnect Preferences:

In the first tab of preferences, specify the path to your literature note folder in the Obsidian vault:

More importantly, make sure that the tag that MarkDBConnect applies matches then one you used in the tag hierarchy when setting up kanban-maker-quickadd.js (step 6). This is done in the Advanced tab:

Actions and Tags

If you are interested in further automation of tagging, you can look into the Actions and Tags addon for Zotero (AKA Zotero Tag). Here's some examples of what it can do:

• Tag newly imported items with #unread and remove the tag when you open the PDF
• Tag items you open in Zotero's reader with a certain tag like #reading or #read
• Remove the #reading tag when you add a #read tag
• Tag annotated items with #read, #annotated, #to-import or whatever

Since Actions and Tags is not integral to the Zotero Kanban Reading List workflow, I'm not going to cover the setup here, but the docs on Github are helpful. Note that the Zotero 7 version of the addon is especially powerful.

Usage summary

Let's wrap this up with a summary of the workflow.

1. In Zotero, use the 1-9 keys to quickly tag items and update their reading status:

Better Bibtex will now auto-export your library and update the bibliography.json file, allowing kanban-maker-quickadd.js to update your kanban with the latest Zotero changes.

2. In Obsidian, run the Update Kanban command in one of the following ways:

• cmd / ctrl + P ▶️ Update Kanban,
• cmd / ctrl + P ▶️ Run Quickadd ▶️ Update Kanban,
• or put the Update Kanban command in a button in the tab bar using the Commander plugin to run it with a click 🖱️

3. Click 🖱️ an item's link to create a literature note on the item.

4. Profit! Do awesome research, a bit more conveniently 🍻

Did you get the gist?

If not, you'll find it below:

• Kanban-maker-quickadd.js gist
• Bonus: My new Zotero Integration template (with update button) gist

If anything is still unclear, reach out on Discord in the feralflora-kanban-zotero-script thread in the #academic-tools channel.

If you appreciate my work, you can buy me a coffee to show your support:
I really appreciated it 🧡

Roadmap

• Enable two-way syncing of reading statuses back to Zotero as tags
• Turn the script into a plugin 🔌 (maybe)

Like what you see?

This guide was made in Obsidian and uploaded using the Share note plugin. Shoutout to Alan Grainger for implementing my feature requests and resolving bugs so that the note looks the same online as in Obsidian!