Replace Obsidian's Pandoc Reference List plugin
Move from the Pandoc Reference List plugin to ZotLit in Obsidian and keep your [@key] citations, metadata, and native Pandoc export working.
- Citations such as
@doe2024,[@doe2024], and[@doe2024, p. 33]keep working as written. Leave them as they are. - Point ZotLit at the same Zotero libraries, and pick the same citation style.
- Change each
[[@citekey]]link by hand, one at a time. - Turn off Pandoc Reference List and check one note.
Migrate the workflow
Your existing citations stay as written: nothing in your notes has to change except [[@citekey]] links and some note properties. Keep your original notes or a backup copy until you check a note at the end.
- In Zotero, check that every paper you cite has a citation key in its Citation Key field. Each cited paper shows a key. Choose your key format before migrating notes, and keep existing keys after the move.
- Open Settings > ZotLit > Zotero. Check that Zotero database points to the Zotero profile that holds your cited papers. The database path is the one with your library.
- On the same page, under Libraries, set Library scope to All libraries, or choose Selected libraries and add the personal and group libraries you used before. ZotLit searches all of those libraries at once.
- Open Settings > ZotLit > Citations. Keep Pandoc citations and Show formatted citations on. Under Formatting, install the Pandoc engine. The engine is installed.
- Install your former CSL style in Zotero. Then open Settings > ZotLit and select that style under Citation and references style. Citations in Live Preview use that style.
- Back in Settings > ZotLit > Citations, under Formatting, set Citation locale to your language, or leave it empty to keep Style default. Citation terms and dates follow that language.
- If you used citation-key tooltips, set Hover action to Citation popover. Hovering a citation shows its reference entry.
- Search the vault for
[[@. Change each one by hand. No[[@link is left that you did not mean. - In Settings > Community plugins, turn off Pandoc Reference List. Keep a record of its settings first. Only ZotLit changes how citations look.
- Open a note that uses your citations and note properties. Check that its citations show formatted in Live Preview. Run ZotLit: Open references, then select Copy bibliography in the References sidebar. The sidebar lists each cited paper, and the reference list is on your clipboard.
| What you have now | In ZotLit |
|---|---|
Citations @doe2024, [@doe2024], [@doe2024, p. 33] | Work unchanged. Keep Pandoc citations on. |
Library selection, live rendering, suggestions, tooltips, CSL style, citation language, [[@citekey]] links | Set them up again in ZotLit using the steps above. |
bibliography files, several bibliography inputs, csl or citation-style paths and URLs | Keep them for native Pandoc; see Export with native Pandoc. |
| Bibliography file as the in-app source, tooltip delay, hidden links in references, click one entry to copy | No ZotLit equivalent (see the next fold-out). |
ZotLit reads Zotero directly for its citations in Obsidian. A bibliography file still serves native Pandoc, but it does not fill the References sidebar.
| Pandoc Reference List | ZotLit |
|---|---|
| Bibliography file for in-app references | Connect ZotLit to the matching Zotero database. |
| CSL path or URL in Obsidian | Install the style in Zotero. Keep the path or URL for native Pandoc if needed. |
| Tooltip delay | Choose Citation popover, Page preview, or Off; set Require modifier key per editing mode. |
| Hide links in references | No matching setting. |
| Click one reference to copy it | Select the entry text and copy it with your usual shortcut. |
For all citation settings and their defaults, see Citation settings.
Pandoc Reference List can treat [[@doe2024]] as a citation. ZotLit counts a [[...]] link as a citation only when it points to the paper's literature note.
For each link, choose:
- If it is only a citation: replace it with
[@doe2024]. - If it is a citation that should also open the paper's literature note: replace it with a link to that note without an alias, such as
[[Doe 2020]](only whenDoe 2020.mdis that paper's literature note). For a page locator, use[[Doe 2020#cite:locator=33]].
After the links are updated, turn on Wikilink citations in Settings > ZotLit > Citations. Do this one by one: the intent and the note names differ for each link, so a vault-wide find-and-replace gets some of them wrong.
| Property | What to do |
|---|---|
bibliography | Keep it only for native Pandoc. ZotLit gets reference data directly from Zotero. |
csl or citation-style | Keep one for a style that Pandoc owns. Do not add zotlit-csl to the same note. |
zotlit-csl | Use it when ZotLit should use a style installed in Zotero. Remove csl and citation-style first. |
lang | Keep it when it is a valid document language such as en-US, de, or zh-CN. ZotLit uses it for that note's citations too. |
citation-language | Change it to lang only when the value is the language of the whole document. Otherwise set Citation locale in settings and remove the property. |
To set a Zotero style and the document language together, run ZotLit: Set citation presentation; it is also in the note's More options menu. Its Document language becomes Pandoc lang for the exported document. Keep one style family per note: the ZotLit filter reports csl-ambiguous when a note has both csl and zotlit-csl. For details, see Per-note citation presentation.
If you see something else
- The References sidebar shows a Reference Error → fix every Reference Error before you go on; see Review, copy, and troubleshoot references.
- The sidebar says "@{citekey} matches multiple items in your Zotero library." → two papers share that key, in one library or in two libraries in your scope. ZotLit does not pick one by library order. Give one paper a different key in Zotero, or narrow Library scope; see Ambiguous citation keys.
- Both plugins change how the citations look → Pandoc Reference List is still on. Turn it off in Settings > Community plugins and test with only ZotLit.
- The ZotLit filter reports
csl-ambiguous→ the note has bothcslandzotlit-csl. Keep only one of them.
Next
- Export note with citations — export a note to Word with ZotLit's ZotLit: Export note with citations.
- Export with native Pandoc — keep bibliography files, several inputs, CSL paths or URLs, and other Pandoc options.
- Pandoc citation workflow tutorial — compare built-in and native export with one note.
Last updated on