Citation Needed: How to Use Logseq's Zotero Integration
If you’ve been on Wikipedia, you’ve probably seen it:
You may have wondered what a citation is, why it’s needed, or how to cite information.[1] Put simply, a citation is a way of indicating where you got information. This information could be a quotation, a paraphrase, or a mention of a specific work or topic. They give credit to the people who created the information.[2] Citations are most commonly used in scholarly writing, but they should be used wherever you are sharing knowledge.
Luckily, several tools exist to make reference management and citation easier. Logseq has a built-in integration with one of them: Zotero. Zotero is a free, open-source reference management software that helps you build your reference library and cite those references in your writing. It can store your notes and PDF attachments, and it has a PDF reader and annotator.
With Zotero’s browser extension, you can clip reference information for articles, websites, YouTube videos, books, and more. Then, you can create citations and bibliographies in almost any citation style. Zotero’s word processor plugins allow you to search your reference library while you write and will generate in-text citations and bibliographies for you.
If you just want formatted citations and bibliographies, you can generate those within Zotero and copy/paste them into your Logseq block or page. Just right-click on the reference entry you want (or select multiple at once) and click “Create Bibliography from Items...” Pick your citation style and whether you want it as a citation or bibliography. Select “Copy to Clipboard” and paste it into Logseq!
If you want more, however, this tutorial will teach you how to set up Logseq’s Zotero integration as well as demonstrate using it within a Zettelkasten workflow. The main focus of that workflow is the reference note and block reference PDF highlights, which Logseq creates for you! But don’t worry about this being too hard to set up: I do not assume advanced knowledge of either Logseq or Zotero, nor do I assume technical knowledge or coding skills.
But, before we can use Zotero inside Logseq, we need to configure Zotero outside Logseq.
Back to basics: Let's get Zotero set up
One of the many reasons Zotero is great is that you don't need an account to use it locally on your computer. However, Logseq requires an API key to access your library, so you need to create an account on https://zotero.org if you don't already have one. With this account, you can access your library online and sync it across devices.
Once you're logged in, click on your user name and go to "Settings."
Click on "Feeds/API" to access your userID and to create a new private key. Take a note of your userID.
Click "Create new private key" and name or describe your key. For the "Personal Library" access settings, you must at least have "Allow library access" checked. I recommend also checking "Allow notes access" if you want to give Logseq access to your notes in Zotero. It can’t right now, but it should in the future. Otherwise, configure your access settings however you like.
Download Zotero, install it, and go to Preferences. If you want Logseq to bring in your PDF files, I recommend setting Zotero up to automatically grab them when you clip articles in your browser. You can also drag and drop PDFs into Zotero, either on their own or onto an existing reference. If they are modern PDFs, Zotero should be able to grab the bibliographic information for them automatically. If not, you will need to create a reference manually (or clip it from somewhere) and drag the PDF onto the new reference.
The Zotero application has no storage limit except for your machine or third-party cloud service. However, your account has a storage limit, and PDFs eat it up really fast. You can pay for more storage (it's pretty cheap), or you can store PDFs outside Zotero and link the attachments. This is what I do using the Zotfile plugin for Zotero.[3]
If you want Zotero to handle your PDFs and other attachments for you, and you don't change any default locations, you can skip this next part and go right to the Logseq configuration.
If you store your attachments elsewhere, you need to tell Zotero about it. I have iCloud Drive, so I have Zotfile automatically rename my PDFs and move them to an iCloud folder.
Alright, back to Logseq
Great. We've got Zotero ready to integrate with Logseq. There's only one more thing to configure before we can actually use the integration.
In Logseq, go to "Settings" and click "Editor." At the bottom, you'll see "Zotero settings." Yep, you guessed it. Click that.
You should see something like the image below. Your fields will look different because I've already edited mine.
- Grab the API key you created and paste it into the “Zotero API Key” field.
- Paste the userID you saved into the “User or Group ID” field.
- Fill in your “Zotero data directory.” On Mac, the default is
/Users/yourusername/Zotero - Edit the other fields to your preference. I recommend toggling on “Include attachment links?” and “Include notes?”.[4] Again, notes don’t work right now, but it can’t hurt to future proof.
- If you're using linked attachments in Zotero, fill in your “Zotero linked attachment directory.” Otherwise, Logseq won't know where to find your files.
And do not click “Add all.” You really don't want your entire Zotero library in Logseq. Zotero has an incredible index and search system as is. Bring references in as you need them.
We have everything set up...what do we do with it
Everyone's workflow and use case will be unique. I'm going to walk you through mine, but what's most important is to think about what you need. With that in mind, you can configure and adjust to meet your needs.
I don't do the kind of long-form writing in Logseq that results in journal articles. The reason for this is that Logseq cannot handle the kind of citation workflow I need for most publishable scholarly writing.
Instead, I use Logseq for my Zettelkasten. The primary way I use Logseq's Zotero integration is to create reference notes and cite references in Zettelkasten notes. The only reason I'm doing that in Logseq instead of Zotero is the ability to see every note that cites a reference. Otherwise, Zotero's PDF annotation and note functions are as good as Logseq's. This is a place where your needs and preferences should guide what you do.
Creating reference notes with Zotero
I am one of those "journal first, page second" note-takers. Even when I'm creating a page, I always try to create it from the daily journal page.
When I know I'm going to cite something or read it to take notes, I open Zotero and type /Zotero in my Logseq daily journal page. A search bar pops up. Because I know what I'm going to cite, I type the author or something from the title to bring up the reference. I click on the reference I want, and it creates a page!
I prefer to use a block property and give it the type Reference. This way, I can query all my reference notes without having a cluttered graph.
Clicking on it brings me to a page like this:
As you can see, the Zotero integration pulls in the bibliographic information from my Zotero library! I recommend checking the entries in your Zotero library as you capture them; the browser extension doesn't always import accurate information, and it might not be formatted how you want.
You can change any of the page properties it creates. I usually unlink the item-type property, as that is not useful information for me. If the author isn’t a page, I’ll create a page for them. I also like to turn the access-date into a page by using the date picker. This date is the day I put the reference in Zotero, so it might be a different date than when I add it to Logseq.
If the reference is audiovisual, I like to embed it in the page somewhere.
The web clipper can grab the author-supplied keywords and other subject headings when used in databases and add them as tags. Logseq includes these tags in the page properties. These tags may or may not be useful to you, and they might be more useful in Zotero than they will be in Logseq, or vice versa. I usually remove them once in Logseq because I don't like them cluttering my graph. I don’t do anything with tags in Zotero, so it’s usually not worth the effort to remove them from everything I capture. If you want to add tags, either in Zotero or Logseq, you absolutely can. You can change anything in the metadata you want!
This is where the magic happens
I’ve created my reference note. Now I can start adding my notes for that reference; I’m following the How to Take Smart Notes or traditional Zettelkasten workflow. Logseq makes this particularly easy for any reference with a PDF because of how incredible its PDF reader and annotation features are.
This reference in my Zotero library has a PDF attachment, so Logseq added that PDF as a link in the note. When I click that link, Logseq opens the PDF. More than that, I can highlight and copy text. And the icing on the cake: Logseq creates block references of my highlights that give me the PDF page number.[5] When clicked, they take me to the location of the highlight in the PDF.
I view my highlights by clicking the icon in the PDF toolbar that looks like a comment box. Because these are block references, I can use them as block references anywhere in Logseq. When I click on one of these block references anywhere in my Logseq database, it still opens the PDF at the location of the highlight. Incredible, right?
I can even highlight images or any other chunk of the PDF by clicking the filled square icon in the PDF toolbar. I showed this to a coaching client of mine who works in medical research; you would think it solved every problem she's ever had based on her reaction.
Note of caution: as of the time of writing, there’s a bug that creates inconsistencies with highlight page properties. I recommend either opening the Annotations Page before you take highlights, or taking your first highlight, using it as a block reference, and then opening your Annotations Page. The second way gets you more page properties. If you take multiple highlights before opening your Annotations Page, it doesn’t bring in the first highlight.
My workflow
To give a better sense of what the Zotero integration looks like in action, I’m going to briefly walk through my process of creating a reference note and citing the work in what I’ll call a Zettel.[6]
An interest of mine right now is the aesthetics of information. A while back, I added an article to my Zotero library related to this topic. I decide I’m going to read it, keeping in mind the topics I’m interested in. I open Logseq and use my Reference Note template[7] on my daily journal page (see below for the template code).
- /
date::
tags::
type:: [[reference]]
template:: Reference note (rn)This template is a blank bullet with block properties. I type /Zotero and search for the title of the journal article.
The tags and type properties are self-explanatory, but I use the date property a bit strangely. I add today’s date in YYYY-MM-DD format instead of using the date picker. I only use this information to sort a queried table of my reference notes by the date I added them. The query is {{query (and (property type reference) (not property tags templates))}} because I don’t want my reference note template in my query results.
Now, as I showed earlier, I can open the page and the associated PDF to start reading, annotating, and indexing. I’m still working out which workflow for highlights I like best. I encourage you to have fun experimenting with workflows! Remember that you can edit the block reference highlight text, either to correct what it pulled or to make your own notes. Either way, it will always return you back to that highlight in your PDF.
Once I’ve read the reference, I have some ideas for Zettels.
When I write my Zettel, I try to include the quotation (or tweet, etc.) that sparked the insight. Of course, I have to cite it. To do that, I use Markdown syntax to insert a footnote. It’s simple: at the end of the sentence after the punctuation (or at the end of the phrase referring to something), type [^1]. Then, in the next bullet or the bottom of the page, whichever is your preference,[8] type [^1]: and insert a page reference to your reference note. I then attribute it to its author via another page reference. If you have more than one reference or if you need to use a footnote for anything else, remember to increase the number each time and adjust if you rearrange your footnotes.
I can go back to my reference note and check my page graph to see what other notes I’ve cited this article in. I can also see any tags associated with it.
In my main graph, I’ll eventually be able to see larger nodes of references I’ve cited a lot and everything I’ve cited them in. I can also see which authors I cite.
And that, I would say, is what you need to know for a basic Zotero workflow!
What about citekeys?
That’s a very good question. One of the options in the Zotero integration is to title your reference note pages as BibTex citekeys, using the Zotero Better BibTeX plugin. Citekeys are usually a text string of the author’s last name, some words of the title, and the publication year. I feel like a lot of people have heard about citekeys and their interoperability, but they’re still unsure as to how or why you might use them.
Usually, citekeys are used in LaTeX documents. You will also see them used in org-mode documents and Markdown documents. When citekeys are in org-mode or Markdown documents, it is because you are going to convert that document to a PDF. How programs like Zettlr and the org-mode export functions do that conversion is through a command-line program called pandoc. To get from org-mode to PDF, these programs will often convert first to LaTeX, hence the need for BibTeX citekeys.
I have some bad news for all of us Logseq users, though: pandoc’s syntax isn’t compatible with wikilinks. That means you can’t insert citations in Logseq as page references. I’m sure someone has already figured out some way to fix that, but I’m not that smart. Instead, you’ll just have to copy and paste your citekeys into your Logseq document following pandoc syntax.
When you’re ready to convert your file, you’ll need to install pandoc. Then, you need to set up the export. The Better BibTeX documentation includes instructions for setting up Markdown/Pandoc export. Then, you’ll need to open a terminal in the directory of your Logseq graph. To convert your document on the command line, you’ll need to type the following, changing directory structures for Windows as needed:
pandoc --lua-filter=zotero.lua --metadata=zotero_csl_style:<INSERT DESIRED CITATION STYLE LANGUAGE HERE> -o DesiredDocumentTitle.docx pages/Existing\ Logseq\ Page.md
Now we have a Word document that can actually interface with the Microsoft Word Zotero add-in. Pretty cool, huh?
There are other features and workflows to experiment with, though. For example, I just saw a plugin that will let Zotero know if you’ve used a reference in Logseq. If you’re using org-mode, you could open your files in Emacs and use some of its amazing org-mode export functions. I actually prefer to do my longform writing in org-mode in Emacs; the export is easy and amazing, and I can get auto-generated bibliographies and use citation styles.[9]
Those workflows, however, will have to wait for another post…
Need more help?
You’re in luck! I’m a librarian who has been teaching Zotero to university students, faculty, and staff for almost a decade, and I’ve led workshops for the Building a Second Brain community. I also take on clients who want coaching, mentoring, and consultation for using Zotero within their knowledge management workflows. If you want extra help, have questions, or are interested in a one-time consultation session or an ongoing coaching arrangement, email me at jaylcolbert [at] gmail [dot]com or reach out to me on Twitter at @_WildeAtHeart.
I highly recommend Dario da Silva’s Logseq Mastery course, which has some information on the Zotero integration. (Full disclosure: I’m a course affiliate. If you’re interested in taking it, it would be super cool of you to do so through my affiliate link.) I had an interesting conversation with Dario about how I use Zotero, which you can watch below:
Finally, see if your local public library offers Zotero workshops—if you have a public library available to you. I can help you through that process if you want!
Footnotes
[1] I’m not going to assume anyone’s familiarity with citation practices.
[2] In fact, there are feminist and other critical approaches to citation which address inequities of who is being cited and who is not.
[3] If you would like help setting Zotfile up, feel free to get in touch with me!
[4] If you plan to export and convert your Markdown notes using pandoc, toggle “Use citekey as your page title?” on and install the Better Bibtex Zotero plugin. I remove the page links for Attachments and Notes because they aren't useful to me, but you might find them useful. Finally, because I'm not exporting my notes or using citekeys, I remove the @ page name prefix. Again, if you aren't exporting and using pandoc, what you put here is entirely your preference. For example, if you're a person who likes using namespaces, you could put a namespace here.
[5] You will probably need to edit the text from the highlight. I’ve noticed that the text isn’t always formatted correctly because of how PDFs display text.
[6] I don’t say permanent note because both reference/literature notes and main notes are permanent notes. There is no standard name for the main notes in a Zettelkasten, so I will use the term Zettel.
[7] Technically, I use a text expander for this, but I do have the template in Logseq should I need it.
[8] I publish my notes using the Hugo static site generator, and it automatically formats footnotes no matter where you’ve placed them.
[9] Jethro Kuan’s How I Take Notes with Org-roam includes a great citation setup with Zotero. The org-mode documentation has more information for using citations and exporting bibliographies.
