How to migrate from Pandoc Reference List
Move a Pandoc Reference List workflow to ZotLit while preserving citation syntax, metadata, and native Pandoc export.
Use this guide to move your citation workflow to ZotLit without assuming feature parity.
After migration, Build a Pandoc citation workflow to compare built-in and native export with one note.
The Pandoc Reference List repository is hosted by the Obsidian Community Archive.
Decide where each part moves
| Classification | Existing behavior | ZotLit destination |
|---|---|---|
| Works unchanged | Literal citations such as @doe2024, [@doe2024], and [@doe2024, p. 33] | Keep the Markdown source. Enable Pandoc 引用. |
| Change settings or syntax | Zotero library selection, live rendering, suggestions, tooltips, CSL selection, citation language, and [[@citekey]] links | Configure ZotLit and audit the affected metadata and links. |
| Continue with native Pandoc | bibliography, bibliography files, multiple bibliography inputs, and standard csl or citation-style paths and URLs | Keep these inputs in a native Pandoc workflow. |
| No ZotLit equivalent | In-app bibliography-file source, tooltip delay, hidden links in references, and click-one-entry-to-copy | Use ZotLit's Zotero-backed controls described below. |
ZotLit reads Zotero Items for its in-app citation features. A bibliography file remains useful for native Pandoc, but it does not supply the 参考文献 Sidebar.
Migrate the workflow
Record the current setup
Record the current bibliography source, selected libraries, CSL style, language, and rendering settings.
Search the vault for these note properties and citation forms:
bibliographycslorcitation-stylelangorcitation-language[[@
Keep the original notes until you finish the verification steps.
Confirm citation keys in Zotero
Confirm that every cited Zotero item has a citation key. ZotLit resolves literal keys against Zotero's native Citation Key field.
Better BibTeX is recommended for generating and maintaining stable keys. ZotLit does not require Better BibTeX when the native field already contains suitable keys.
Choose your key format before you migrate many notes. Avoid changing existing keys after the migration.
Connect the Zotero database
Open Settings > ZotLit > Zotero. Confirm that Zotero 数据库 points to the profile that contains your cited items.
On the same page, under 文库, set 文库范围 to 所有文库, or choose 选定文库 and add the same personal and group libraries you used before.
ZotLit searches the complete scope at once. When one citation key matches several items, ZotLit reports an Ambiguous Citation Key. It does not choose an item by library order.
Configure in-app formatting
Open Settings > ZotLit > 引文.
- Keep Pandoc 引用 on.
- Keep 显示格式化引用 on.
- Under 参考文献, install the Pandoc 引擎.
- Install your former CSL style in Zotero.
- Select that style under 参考文献样式.
- Set 引用语言, or leave it at 样式默认.
Set 悬停行为 to 引用弹出框 when you previously used citekey tooltips. ZotLit has modifier-key controls for each editing mode, but no tooltip-delay setting.
Migrate note metadata
Apply these rules to each affected note:
| Property | Migration rule |
|---|---|
bibliography | Keep it only for native Pandoc. ZotLit's in-app features and built-in export get bibliography data from Zotero. |
csl or citation-style | Keep one of these for a Pandoc-owned style. Do not add zotlit-csl to the same note. |
zotlit-csl | Use this instead when ZotLit should resolve 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 also uses it for that note's citations. |
citation-language | Convert it to lang only when the value describes the complete document. Otherwise, set the vault 引用语言 and remove this property. |
To set a Zotero-installed style and document language together, run:
ZotLit: 设置引文呈现方式The same action appears in the active note's More options menu. Its 文档语言 value becomes Pandoc lang for the complete exported document.
Choose one style owner
A native Pandoc document can use standard csl or citation-style, or
ZotLit can resolve zotlit-csl. Keep only one family. The ZotLit filter
reports csl-ambiguous when a document contains both csl and
zotlit-csl.
Audit citekey links one at a time
Pandoc Reference List can treat [[@doe2024]] as a citation. ZotLit's Wiki 链接引用 setting has a different contract.
Review every [[@citekey]] occurrence and choose its intended result:
- Replace it with
[@citekey]when it is only a citation. - Replace it with an unaliased link to the correct ZotLit Literature Note when it must cite and open that note.
For example, use [[Doe 2020]] only when Doe 2020.md is the Literature Note for that item. Add #cite:locator=33 when the link cites a locator: [[Doe 2020#cite:locator=33]].
Enable Wiki 链接引用 after the Literature Note links are valid. Do not use a bulk replacement because link intent and note names differ by occurrence.
Disable Pandoc Reference List for the test
Keep your recorded settings, then disable Pandoc Reference List in Settings > Community plugins.
Test rendered citations with only ZotLit active. This keeps both plugins from changing the same citation display.
Verify one representative note
Open a note that contains the syntax and metadata you migrated.
- Confirm that its literal citations format in Live Preview.
- Run ZotLit: 打开参考文献.
- Hover a citation and inspect the 引用弹出框.
- Open its Literature Note, Zotero item, and attachment where available.
- Select 复制参考文献 in the 参考文献 Sidebar.
Resolve every Reference Error before you continue. In particular, change duplicate citation keys or narrow 文库范围 when a key is ambiguous.
Choose an export workflow
Use ZotLit: 导出带引文的笔记 for ZotLit's built-in DOCX or HTML export.
Continue with native Pandoc when you need bibliography files, multiple inputs, standard CSL paths or URLs, or other Pandoc options.
Behaviors without a direct equivalent
- Bibliography file for in-app references: connect ZotLit to the matching Zotero database instead.
- Arbitrary CSL path or URL in Obsidian: install the style in Zotero. Keep the path or URL for native Pandoc when required.
- Tooltip delay: choose 引用弹出框, 页面预览, or 关闭. Configure modifier-key requirements by editing mode.
- Hide links in references: ZotLit has no matching citation setting.
- Click one reference to copy it: select the entry text and use your normal copy shortcut. The row click targets citation navigation and item actions.
See also
Last updated on