ScholarWeft

ScholarWeft weaves your ideas, references, and finished scholarly output into a connected workflow. Its purpose is to allow you to incubate and finish complex academic writing projects — even long books — organically inside manageable, interlinked Obsidian notes. It integrates four processes:

• Creating automatically synced literature notes from your Zotero references, notes, and annotations using a rich import template.
• Finding the most relevant works to cite and import using a ranked search of Zotero items by citekey, title, author, abstract, and publisher
• Connecting your works cited to your universe of thoughts, treating them as Zotero links while also rendering them as formatted citations
• Importing and exporting your scholarly writing while keeping active Zotero citations, producing publication-ready academic articles and books with sophisticated provided and customized templates

ScholarWeft's unique linked citations weave every work you cite into your interconnected Obsidian thought universe. The citation [[@sanchez2009|see @, p. 25]] is simultaneously a formatted inline citation — "(see Sanchez 2009, 25)" — and an Obsidian wikilink to that source’s literature note. Other citation plugins can either link to a literature note ([[@sanchez2009]]) or render pandoc-formatted citations ([see @sanchez2009, p. 25]) but don’t allow you to integrate publication-ready citations as nodes in Obsidian's note network visualized in backlinks and graphs.

Beyond linking your scholarly notes and references, ScholarWeft allows you to keep your writing process in Obsidian while connecting it to the world beyond Obsidian. Bring your word processor documents into Obsidian’s link network by importing DOCX and ODT documents to Obsidian notes with linked citations and literature notes for each cited work. Export an Obsidian note or compile a series of notes as a publication-ready DOCX, ODT, or PDF document with formatted, live Zotero citations.

Documentation

• Setup — install and first steps
• Dependencies — what each feature needs, and where to get it
• Zotero — connection modes, port, libraries
• Bibliography files — .bib/CSL sources, per-note overrides independent of Zotero
• Linked Citations — the citation syntax
• Citations and References — formatting, tooltips, the reference sidebar
• Searching for References — two search levels, how results are matched and ranked, and search tips
• Creating Literature Notes from Zotero — where notes live and how to create them from Zotero items
• Document Import and Export — compile a longer document from a series of notes, export to markdown, DOCX, ODT, PDF
• Commands — the full command list
• Mobile — iOS/Android behaviour

Features

Most features work with no external tools (no Pandoc, no Zotero) when you use a bibliography file. The ones that don't note it inline; see Dependencies for details.

Citations

• Linked citations — [[@smith1992|see @, p. 6]] → (see Smith 1992, 6): real Obsidian wikilinks and publication-ready formatted citations. Cite several works by placing them together — [[@a]] [[@b]] → (Author A Year; Author B Year). See Linked Citations.
• Insert full dynamic references in body text — [[@key|reference]] or [[@key|ref]] inserts the formatted bibliography entry. Several citations in a row, like [[@a|reference]] [[@b]] [[@c]], yields a reading list. They render live in Obsidian and become plain formatted text when exported. See Inserting full references.
• Conventional pandoc citations — [@key], [see @key, p. 25] render too, and commands convert between formats losslessly.
• Live reference sidebar — a searchable list of every citation in the current note, with copy and jump buttons.
• Insert bibliography at cursor and bibliography snapshot (save a note's citations as a .bib, colour-coded by sync status).
• Search Zotero for references to cite while type, ranked by meaning — while typing, entering @ searches citekey, author and title; @@ adds abstracts, publisher and containing work. Search is case-, accent- and spelling-variant-insensitive, and terms can be in different fields. Write each term as its own word — soc crit finds social critique — and a hyphenated compound (anti-colonial) matches either spelling. Results are ordered by how meaningfully they match — a citekey, then author-with-title, then an exact title phrase, then title words, then the @@ fields — so a title match is never buried by an abstract one. The popup shows the result count and, for @@, an excerpt of the abstract where your terms were found. See Searching for References.
• Quick insertion — in the search popup, Enter inserts a linked citation ([[@key]]) and ⌘/Ctrl+Enter a Pandoc one ([@key]); inside an open bracket only the closer you still need is added.
• Citation decoration and tooltips — colour-coded status; hover for a formatted preview, literature-note link, and Zotero link.
• Mobile support — tap citations in reading mode, long-press in the editor. See Mobile.

Literature notes from Zotero items

• Import and update from Zotero — The command Add Literature Notes/Citations (search and filter) opens a search-and-filter window that searches all your enabled libraries inside Obsidian using the same search methods used to locate citations (see above). It can create literature notes, insert citations, or both. You can filter for items of a certain type; in a collection; containing notes, attachments, or annotations; and for notes not previously imported to Obsidian (or all references). You can order by search ranking or ascending or descending alphabetical order. See Literature Notes.
• Literature note creation — While editing, create notes for cited works from the sidebar, tooltip, or command palette. ScholarWeft's default template provides comprehensive bibliographic data in the note’s frontmatter (every item type's own fields, its Zotero collections) and rich annotation callouts. See Literature Notes.

Zotero and file-based bibliographies

• Native Zotero 7/8 API — no Better BibTeX needed to resolve and format citations (BBT still required for Zotero 6, and still the easiest way to auto-generate citekeys). See Zotero.
• Multiple bibliography sources — any number of .bib/CSL-JSON/CSL-YAML files plus Zotero, merged; Zotero wins on conflicts. See Bibliography.
• Citekey and li sync — update citations and literature notes across the vault if your citekeys change; images attached from annotations are also renamed.

Document import and export (desktop only)

• Compile and export a note or a multi-note outline as markdown, DOCX, ODT, or PDF with one command, with fine-grained options (TOC, footnotes or endnotes, figure captions, custom styles). See Document Import and Export.
• Import DOCX/ODT documents as markdown notes, converting their Zotero citation fields to linked citations.
• Standard Obsidian and custom callouts and markdown → DOCX/ODT/PDF styles — Markdown Attributes / Extended Markdown Syntax styles are converted automatically; styles undefined in the template get a highlighted sentinel style so you can easily locate and define them.

Requirements at a glance

Basic citation work needs nothing installed. Document import/export and live Zotero fields require installing some combination of Python 3, Pandoc, Zotero/Better BibTeX, LibreOffice, and/or a LaTeX distribution — see Dependencies for the exact mapping and download links. The plugin detects what is installed and greys out options that can't run.

Install via BRAT

1. Disable Restricted Mode, then install and enable BRAT from the Community Plugins list.
2. In BRAT's settings, add nebedaay/ScholarWeft to the Beta plugin list.
3. Enable ScholarWeft in Community Plugins. BRAT keeps it updated.

New to all of this? Setup is a complete, click-by-click walkthrough, and it opens with a setup script that can do the whole thing for you — install/update the Obsidian and Zotero apps, add ScholarWeft to Obsidian and Better BibTeX to Zotero, switch on Zotero's local connection, and install the document tools (Python, Pandoc, LibreOffice, LaTeX, fonts). It is interactive (asks before each step), safe to re-run, and prints a summary of what succeeded/failed/was skipped. Copy the one-line command for your OS from the top of Setup.

Network use and file access

ScholarWeft works offline for its core features (bibliography files you supply, citation rendering, the reference sidebar, and literature notes from .bib files). Some features contact services. Each is listed here in full; nothing is sent anywhere else, and the plugin collects no telemetry of any kind.

Feature	Contacts	Why
Zotero integration	http://127.0.0.1:<port> (your own computer)	Reads your local Zotero library, items, annotations and attachments. Nothing leaves your machine.
Import literature notes from Zotero	http://127.0.0.1:<port>/better-bibtex/cayw	Opens Zotero's own picker dialog (needs Better BibTeX). Local only.
Citation style/locale download	raw.githubusercontent.com (CSL locales), www.zotero.org/styles/, the Citation Style Language repository	Downloads the one CSL style or locale file your note asks for, then caches it in .scholar-weft/. Only when the style isn't already installed locally.
"Open in Zotero" / DOI links	doi.org, your system's default browser	Opens the item's page when you click a link. Nothing is sent automatically.

Files outside your vault: the desktop-only document import/export features run external programs (Python, Pandoc, LibreOffice, LuaLaTeX) and read or write the source and output files you choose, including absolute paths you enter. This is required to compile and export DOCX/ODT/PDF documents. On mobile, these features are unavailable.

Companion plugins

ScholarWeft creates and refreshes literature notes itself — no companion plugin is required, and ScholarWeft never downloads or installs another plugin. If a feature benefits from a companion plugin, the settings page links you to Settings → Community plugins so you can install it yourself the normal way. Autocomplete (@ for citekey, author and title; @@ to add abstracts and publication details) uses ScholarWeft's own index.

Coming from ZotLit? ScholarWeft does not integrate with ZotLit, but it recognises notes ZotLit created (they carry a zotero-key property and ZotLit's managed region) and can convert them to ScholarWeft's format — on conversion, ScholarWeft takes over the note and ZotLit stops managing it. Notes you leave alone stay ZotLit's; ScholarWeft still links to them for citations, it just does not update them. See Literature Notes.

Plugin API

const plugin = app.plugins.plugins["scholar-weft"] as { api?: ScholarWeftApi } | undefined;
if (plugin?.api?.version === 1) {
  await plugin.api.focusReferenceListView();
  const citekeys = await plugin.api.getCitekeysForFile(app.workspace.getActiveFile() ?? undefined);
}

Credits and lineage

ScholarWeft is a fork of Bripey Citation Suite by 112345brian (which is itself a fork of Pandoc Reference List by mgmeyers, maintained by obsidian-community). The upstream authors are credited as contributors to this project.

• Bripey Citation Suite by 112345brian — the direct upstream fork
• Original Pandoc Reference List plugin by mgmeyers, maintained by obsidian-community

Both are licensed under the GNU GPL; ScholarWeft is distributed under the same license, as required.

Published with the upstream author's permission. ScholarWeft is listed in the Obsidian community directory with the written approval of Bripey Citation Suite's author: https://github.com/112345brian/knowledge/issues/11

This fork incorporates changes from:

• astroHaoPeng/alp-obsidian-pandoc-reference-list — file-relative bib paths, multiple bibliography files, auto-update on rename
• wjvg-gif/obsidian-pandoc-reference-list-zotero8 — native Zotero 7/8 API mode
• sjelms/obsidian-pandoc-inline-citations — DOM fallback fixes, wikilink alias parsing

Diacritic normalization approach credited to akhmialeuski/obsidian-citation-extended (MIT).

See NOTICE.md for full license attributions.