Jorrit van der Heide385 downloadsWork through your Zotero library as a reading queue, and keep a record of what you decided.
Work through your Zotero library as a reading queue, and keep a record of what you decided.
Works well with Due Credit, which exports a note to Word, PDF, Markdown or LaTeX with its links turned into real citations, and Tag Along, which lets you browse your papers by reading status. See Works well with.

You run a search, skim a page of abstracts, and save thirty papers to Zotero. You read four of them properly. The other twenty-six you judged in a few seconds each: too technical, wrong field, maybe later. Those were real decisions, but they only lived in your head. A year later one of them turns up in another search, you can't remember whether you already looked at it, and you read the abstract all over again. And when your supervisor or a reviewer asks how you chose your literature, you have to piece it together from memory.
Reference managers help you collect papers and annotation tools help you read them, but neither keeps track of the choosing. Paper Trail does. It keeps one list of what is left to do for each paper, from the moment you save it to Zotero until you have written down what it argues. You read in Zotero, where your annotations live. When you finish a paper, you say what came of it, and Paper Trail writes its note with your annotations already in it and puts the cursor where you write the claim. When you drop a paper or park it for later, it keeps the reason you gave, and those reasons export as a table for your methods section.
Paper Trail needs Obsidian 1.13 or later, on desktop.
The first time it loads, Paper Trail opens the queue in the sidebar and checks whether Zotero is answering. If it isn't, the queue tells you so instead of showing an empty list. Then:
Not sure where to start? Next opens the task that will go stale first.
In a paper's note, Paper Trail only writes a fixed list of properties, the annotations section, and the Claim and Assessment headings. Every other property and every word you wrote are yours, and a refresh from Zotero leaves them alone. There are tests to make sure it stays that way. Section 13 lists exactly what it reads and writes.
It only talks to Zotero, on your own computer. It doesn't read files outside your vault and doesn't run any programs.
Every change is tested. Every release is built in public on GitHub, and you can check that the file you installed is the one GitHub built. Section 13.5 shows how.
If you want to work on the plugin, or build something on top of its notes:
Paper.md is yours to edit.[[citekey]] links to the paper's note, and
Due Credit exports it as a citation. Its Insert
citation picks a paper from your bibliography and writes the link.The reading model comes from S. Keshav's How to Read a Paper: you read a paper in passes that each cost more time than the last, and after each pass you decide whether the next one is worth it.

Reading holds the papers that are worth an hour and that you haven't read yet. Every paper under Papers from that doesn't have a note in your vault shows up here, unless you turned on triage for where it came from. Those rows come straight from Zotero, and no file is made for them until you decide something. Clicking a row opens the PDF in Zotero's reader, and reading doesn't write anything to your vault. When you're done, the tick asks what came of it:
The first two take you to the paper's note, which is created at that moment if it doesn't exist yet. The cursor is under the Claim heading, with your annotations right below it.
Claim is the other half of Keshav's second pass. His test is that you should be able to summarize the main thrust of the paper, with supporting evidence, to someone else, and this is where you do that: one or two sentences in your own words about what the paper argues, and which other work it agrees or disagrees with. Tick it off when you've written it. If the heading is still empty, the tick offers to take you there first.
Assessment is the third pass, for the few papers you promote. Now that you can summarise the paper, you argue with it. When you tick off the claim of a promoted paper, Paper Trail takes you straight to its assessment, while the paper is still fresh in your mind.
Triage is optional, and you switch it on per source, with the switch next to each one under Papers from. Leave it off where you skim abstracts in your browser and only save what you mean to read. Then saving a paper was already the decision, and it goes straight to Reading. Turn it on where papers arrive that you haven't made up your mind about, like a lab's shared reading list in a group library or a collection you fill from database searches. Each paper from there first shows up with its title, venue, year and abstract, and you choose one of three answers: drop it (and say why), queue it, or mark it as already read.

You can also switch off Claim and Assessment, under Written passes. With only the claim, there's no third pass to promote a paper to. With neither, Worth summarising becomes Done with it, and a paper you've read is filed as read. That suits you if you write by theme, and your annotations are all the note you need. Switching a pass off only changes what Paper Trail offers you. Your notes stay as they are, and a paper you promoted before you turned assessments off still needs its assessment.
The stages and the reading statuses themselves are fixed. Paper Trail is one particular way of working through your reading, and the queue can only tell you what to do next because it knows what each stage means. You can switch a stage off, but you can't add, rename or reorder them.
Below the stages are two sections for papers that don't need anything from you right now. Deferred holds the papers you parked, with a count, so a paper you meant to come back to stays in sight. Hover over a row to see what you said had to happen first. Filed holds the papers you're done with, newest first, whether you dropped, read, summarised or assessed them. Neither section counts toward what's left to do.
A deferred paper comes back by itself. When you defer a paper, you say what has to happen first and choose when to look at it again: once you've read another paper that's still unread, in two weeks, in one, three or six months, or never. When that moment comes, the paper goes back to the stage it left, Reading or Claim, with a clock before its title and your condition in its tooltip, and Next can offer it to you. Its note keeps saying it's deferred until you decide something new: read it, defer it again, or drop it.

Clicking a row takes you to the work itself: Zotero for a reading, the heading for a claim or an assessment, the triage dialog, or the paper's note from Deferred or Filed. The button at the end of each row, which appears when you hover over it, does the same and tells you beforehand where it will take you. The row of the note you're in is highlighted. Clicking it never moves your cursor away from what you're writing, but its button still takes you back to the heading.
Next opens whatever will go stale first: a claim before an assessment, both before a new paper, and triage last. A paper you read yesterday fades from memory quickly, while one you haven't opened yet will triage just as well in March.
The search button opens a box that filters the pane to papers whose title, file name (the citation key, with Better BibTeX), or deferral or drop reason contains every word you type. Every section with a match opens, including Deferred and Filed, and shows all its matches. Next still works from the whole queue. Press Escape to close the search.
Right-click a row, or a paper's note in the file explorer, and you get the same menu: first what the row's buttons do, such as Reading finished and Open in Zotero, then the reading statuses you can move the paper to. Set reading status offers the same statuses from the command palette and from the status at the top of every paper, and tells you where each choice will put it. On a paper you've already read, the choices say what they do: assess it too, skip the assessment, reopen a claim or assessment you ticked off too early, read it again, come back to it later, or leave it out. Whatever you pick, everything you wrote stays.
Paper Trail never blocks you: there's no fixed order, and no stage stays locked until you've finished an earlier one.
The queue lives in the sidebar: click the ribbon icon or use Open queue. Insert queue block puts the stages in a note of your own, such as a dashboard. The block only shows what's outstanding, without the toolbar and without Deferred and Filed, so your note doesn't fill up with everything you've already finished.
Each paper gets one note, named after its Better BibTeX citation key, or after its author, title and year if you don't use Better BibTeX. Below the properties, which hold what Zotero knows about the paper and what you decided about it, the note starts with a title, links to the item and the PDF, and your annotations:
# Notes Toward a Method
[Zotero](zotero://select/library/items/ABCD2345) · [PDF](zotero://open-pdf/library/items/EFGH6789)
<!--paper-trail-->
## Annotations
> [!quote|zotero-yellow]
> a passage you highlighted in Zotero (p. 4) ^zt-JKLM2345
a note you wrote on it
<!--/paper-trail-->
The Claim heading is added above the annotations once the paper needs a claim, and the Assessment heading once you've ticked off the claim. That way a paper you dropped after reading the abstract stays three lines long, instead of carrying an outline of work that never happened. Under each empty heading, a question is shown faintly, and it disappears as soon as you start typing. It's never written to the file.

A paper that doesn't need anything from you opens in reading view instead of the editor. It switches the moment you tick off its last pass, defer it or drop it, and goes back to the editor when you put it back on the list. Its title bar has a refresh button, the paper's next step, and its reading status, which opens the status chooser when you click it. On a deferred or dropped paper, hover over the status to see the reason you gave.
The annotations are every Zotero annotation that has text or a comment: highlights, underlines, and notes on a page. They're refreshed whenever you open the note while Zotero is running, and only written when something changed. Each one gets an anchor made from its Zotero key, so a link to a single passage still works after a refresh. A passage that runs across a column or a page arrives as one line. If you underline terms and keep highlights for passages, turn off Include underlines and only the underlines you commented on come through.
Each passage keeps the colour you gave it in Zotero. It's written as a quote
callout, > [!quote|zotero-red], so you can search a colour by name, and
without Paper Trail it's still an ordinary quote callout. Annotations that came
inside the PDF, in a colour Zotero's reader doesn't offer, show up as a plain
quote.
Right-click a passage and choose Show in Zotero to open the PDF at that annotation. This works in reading view and in the editor, where it's the line the cursor is on.
New notes are made from Paper.md in the template folder. Paper Trail puts it
there when it makes its first paper note, and after that it's yours to edit.
{{title}} becomes the paper's short title in Zotero, or its full title if
there is no short one, and {{links}} becomes the links to the item in Zotero
and to its PDF. Case and spaces inside the braces don't matter. A placeholder
Paper Trail doesn't recognise is left as it is, so a typo shows up in the note
instead of silently deleting a line.
A literature note that only repeats the paper doesn't give you much. The abstract already says it better, and it's one click away in Zotero. So a note has a different job. It should be the smallest thing that can stand in for the paper when you're making your own argument.
Here's a simple way to check. Say you're writing a paragraph that cites the paper. If you'd have to open the PDF again to remember what it was about and what you thought of it, the note hasn't done its job yet. Opening it to check a quote is fine, and that's what the page numbers on your annotations are for.
Most papers make sense when you read them. The trouble, over the years of a PhD, is that you forget them. Two years from now your own reading will feel like someone else's, and a note that only made sense while the paper was fresh won't help you much by then.
That's why there are two separate headings. Claim is what the paper argues, in your own words. If you can't put it in your own words now, you won't manage it later when you're writing either. Keep it to one or two sentences. A page-long summary is something you'd have to reread, and then you're back where you started. Assessment is where you argue with the paper: what doesn't hold up, what it takes for granted, and what the evidence really shows. Nobody else can write that part for you. A note with nothing in it to push against tends to get cited as background, and that's the kind of citation that does the least for a thesis.
Keeping the two apart means that when you're writing, you always know whose idea you're looking at, the paper's or yours. That matters for more than tidiness. Once they're mixed up, it's easy to present a paper's idea as your own without meaning to, or to cite a paper for something it never said.
The rest comes down to time. Four hundred papers at twenty minutes a note is over a hundred and thirty hours. That's why an abstract gets about twenty seconds in triage and a claim gets two sentences, and why only the papers you promote ask for an assessment. Whatever else you'd like a note to hold has to fit in those hours too.
One thing is worth the time, though. A literature review is more than a list of papers. It makes a claim about a field: who agrees with whom, what everyone takes for granted, and where the gap is. Those are connections between papers, and that's where your own contribution comes from. So the claim asks for two things, what the paper argues and what it argues with or against. It asks right after you've put the paper's argument into words, because that's when the second question is easiest. You still remember that it contradicts something you read in March.
Write against [[okafor2019sampling]] in a claim, and the link does three
things. It reads as a citation, exports as one with Due Credit, and adds this
paper to the backlinks of Okafor's note. Over time, the backlinks pane shows
you which papers in your literature answer which, and that's exactly what
you'll want to know when you write about them.
A citation is a link to the paper by its citation key: [[okafor2019sampling]].
With Better BibTeX, notes are named after their key, so the link opens the
paper's note, shows it on hover, and counts in its backlinks. A key with a
character a note's name can't have, like the colon in smith:2017, gives the
note a dash instead, smith-2017, and the key stays in its citekey property.
Typing [[ finds papers by key rather than by title.
Paper Trail leaves inserting citations to Due Credit. Its
Insert citation lets you pick a paper from your bibliography (the .bib
file Better BibTeX exports) and writes the link for you, to the paper's note if
it has one. Its Add page to citation adds a page to a link you typed
yourself. Both moved there from Paper Trail in 2.0.0.
Insert annotation first asks which paper you're quoting, then shows that paper's annotations to search. Only papers with annotations are listed, the most recently changed first. It writes the passage you pick as a quote with a citation to its page:
> In offline interactions, heuristics help individuals judge. [[a|a, p. 7]]
The page number and the anchor from the paper note are left out of the quote, and the page goes into the citation instead. The quote is a copy, so changes you make to it stay in your note, and it doesn't change when you edit the annotation in Zotero. It works without Zotero running, but it only knows the annotations that were synced the last time you opened each paper's note. It won't insert into a paper's annotations section, because that section is rewritten every time the note is refreshed from Zotero.
Paper Trail doesn't run pandoc itself. Exporting is what Due Credit does. It runs pandoc on a note and turns these links into real citations in Word, PDF, Markdown or LaTeX. See Works well with.
Don't put your own parentheses around a citation. The export adds them, so
([[a]]) would come out as "((A 2024))".
Dropping a paper doesn't delete anything. The note stays, and so does what you decided about it:
| Property | |
|---|---|
reading |
what the paper is worth to you: untriaged, queued, promoted, deferred or dropped |
reading-progress |
how far you got: read, summarised, assessed, or empty |
reading-date |
when the status last changed |
triaged-date |
when you first made a decision about it, written only once |
reading-reason |
why, when you dropped or deferred it |
reading-until |
for a deferral, the date it comes back |
reading-after |
for a deferral, the Zotero key of the paper it's waiting for |
reading and reading-progress are kept apart on purpose. One is what you
think of the paper, and the other is how far you've got with it. That's why
dropping a paper you had already summarised doesn't undo the summary, and why
picking it up again brings it back to where you left off. A refresh from Zotero
never changes any of these fields.
Export excluded papers writes Excluded papers.md to the root of your
vault: every paper you dropped or deferred, oldest decision first, with its
authors, year, date and reason, and a link back to each paper. It's plain
markdown, ready for an appendix or a methods section, and it's rewritten every
time you run the command. It only ever replaces a file it made itself, so if
you have a note of your own with that name, it's left alone.
The queue is one way to look at these fields. They're ordinary properties, so Obsidian's Bases, Dataview or anything else that reads properties can show them in its own way. If your reading process has steps the queue doesn't know about, add your own properties next to these and build the view you want on top of both.
For example, a base listing every paper you parked, saved as Parked.base, with
Literature as your papers folder:
filters:
and:
- file.inFolder("Literature")
- reading == "deferred"
views:
- type: table
name: Parked
Add reading-reason and reading-until as columns from the view's properties
menu. In a filter, a key with a hyphen is written as note["reading-progress"],
so papers you've read but not yet summarised are
note["reading-progress"] == "read".
You can also change reading by hand, or with another plugin, and the queue
follows along, because the note is the record and the queue only reads it. A
value Paper Trail doesn't recognise counts as untriaged, which puts the paper
back in front of you. The fields around it, like the reason, the dates and the
status tag, stay as they are until you next make a decision in Paper Trail.
None of the commands come with a hotkey, so they won't clash with the ones you already use. You can set your own in Settings → Hotkeys.
Queue
Paper Trail: Open queue - Shows the queue in the sidebar. Also available from
the ribbon.Paper Trail: Next - Opens the task that will go stale first.Paper Trail: Insert queue block - Puts the stages in the note you're editing.Papers
Paper Trail: Set reading status - Queue, promote, defer or drop the open
paper, reopen a claim or assessment, or send it back to be read again.Paper Trail: Refresh paper from Zotero - Refreshes the open paper right away
and lets you know. Opening a paper already does this quietly.Paper Trail: Link existing notes to Zotero - Turns literature notes from
another plugin into paper notes, matched by citation key. It tells you what
will change before it changes anything.Citations
Paper Trail: Insert annotation - Inserts a passage from one of your paper
notes as a quote, with a citation to its page.Record
Paper Trail: Export excluded papers - Writes Excluded papers.md, with every
paper you dropped or deferred and why.Zotero
At the top, Connection says whether Zotero is answering and whether Better BibTeX is installed. Click the arrow to check again.
| Setting | Default | |
|---|---|---|
| Papers from | My library | Where the queue gets its papers. That can be your library, a group library, or collections in them, if your library holds more than the papers for this thesis. Add them, delete them, or drag them into order. If a paper is in more than one, it counts for the first. Papers that already have a note stay in the queue, even outside these. |
| The switch next to each source | Off, on for a group | Under Papers from: on, papers from there that you haven't decided about go to Triage first. Off, they go straight to Reading. |
| Include subcollections | On | Also bring in the papers from the collections inside each collection under Papers from. |
| Include underlines | On | Show underlines in a paper's annotations. Turn it off if you underline terms and highlight passages. An underline you've commented on still shows up. |
Vault
| Setting | Default | |
|---|---|---|
| Template folder | Templates/Paper Trail |
Where Paper.md lives. See The template. |
| Papers folder | Literature |
Where the paper notes go, one per paper. |
| Status tag | Empty | Also write each paper's status as a tag, such as status/queued. Leave it empty for no tag. The tag is only a copy, and Paper Trail itself goes by the properties. |
Papers
| Setting | Default | |
|---|---|---|
| Item key property | zotero-key |
The property that holds the Zotero item key. If you already have literature notes, set it to the property they use and Paper Trail recognises them as they are. If you change it later, notes with the old property aren't recognised anymore. |
| Show reading status on papers | On | Show a paper's status in the title bar while you edit, and at the top of the note in reading view. Click it to change the status. Turn it off if you keep the properties panel open, where you'd see the same word twice. |
| Quieter notifications | Off | Only show failures and warnings. |
| Written passes | Claim and assessment | What comes after reading: both passes, only the claim, or none, which files a paper as soon as you've read it. |
| Claim heading, Assessment heading | Claim, Assessment |
The headings the two written passes go under. Only shown for the passes you use. |
| Claim prompt, Assessment prompt | A question | The faint text under each empty heading. Leave it empty to turn it off. |
A setting that has to agree with your vault or Zotero says so right under it: a source under Papers from that Zotero doesn't have anymore is marked "(not in Zotero)", the Claim and Assessment headings say how many papers already use them before you rename one, and Status tag says how many papers still have the old tag after you change it.
I made these too. Each one does one thing and works on its own, but they fit together nicely.
Due Credit exports a note
to Word, PDF, Markdown or LaTeX with pandoc, and turns your [[citekey]] links
into real citations, with a reference list in the citation style you choose. It
also inserts them. Its Insert citation picks a paper from your
bibliography and links to the paper's note, so every place you cite a paper
turns up in its backlinks. When it exports, a link to a paper's note cites the
key in that note's citekey property, so the link still cites the right paper
after Better BibTeX changes the key. Its README lists what exports as what.
If you install one companion, make it this one: Paper Trail helps you read the papers, and Due Credit helps you cite them and gets the chapter out of your vault.
Tag Along shows your vault
as a folder tree built from your tags. Set Status tag to status, and your
papers show up in Tag Along under status/queued, status/summarised and so
on, next to your other tags. That way you can browse your reading by status and
narrow it down by topic.
Paper Trail runs entirely on your device. It never connects to the internet and doesn't send anything anywhere.
http://127.0.0.1:23119/api/... for items, collections,
annotations and the group libraries you're in. These are read-only. Paper Trail never changes anything in
Zotero. It reads your own library, and only the group libraries you add under
Papers from. It reads a whole library even when Papers from names a
collection, and picks out the collection's papers itself.http://127.0.0.1:23119/better-bibtex/cayw?probe=true only
asks whether Better BibTeX is installed, without opening anything.zotero:// links open an item or a PDF in Zotero. Paper Trail only follows
them when you click a row or a link, or choose Show in Zotero on an
annotation.title, aliases, authors, year, citekey,
zotero and the item key property), the status tag if you set one, the
region between <!--paper-trail--> and <!--/paper-trail-->, and the Claim
and Assessment headings once a paper needs them.Paper.md in the template folder, when a paper note is made and
there's no file with that name. If the file is there, edited or not, it's
never overwritten.Excluded papers.md in the root of your vault, only when you run
Export excluded papers, and only over a file it made itself.data.json in the plugin folder.Every change I push is built, checked with ESLint and the official Obsidian ESLint plugin, and tested with Vitest. Nix builds it a second time, on its own.
Releases are built by GitHub Actions from the tagged code, after the same
checks. A release only goes out when its tag matches the version in
manifest.json, and every action it uses is pinned to an exact version. Each
release comes with a signed attestation from GitHub, which records what it
was built from. To check that the main.js you installed is the one GitHub
built:
gh attestation verify main.js --repo jorritvanderheide/obsidian-paper-trail
Have a look at the FAQ first. It covers the things people run into most, like Zotero not answering or annotations that don't show up. If something still doesn't work, or you have an idea, please open an issue. Found a security problem? Please report it privately, the way the security policy explains.
The code lives on Codeberg, with a copy on GitHub.
Paper Trail is free. If it's useful to you and you'd like to give something back, you can do that on Liberapay:
Copyright © 2026 Jorrit van der Heide. Licensed under the EUPL-1.2.