Citation Extended

by akhmialeuski
5
4
3
2
1
Score: 55/100

Description

Obsidian Citation Extended. An extended plugin that connects your academic reference manager with Obsidian, enabling you to search references and create literature notes for papers and books.

Reviews

No reviews yet.

Stats

12
stars
3,881
downloads
1
forks
132
days
4
days
4
days
82
total PRs
0
open PRs
0
closed PRs
82
merged PRs
20
total issues
0
open issues
20
closed issues
353
commits

Latest Version

5 days ago

Changelog

This patch release clears the last finding of Obsidian's community plugin scanner for 0.7.4. The plugin now requires Obsidian 1.13, which the settings pages introduced in 0.7.4 are built on, and its lint runs the same rules the scanner reports from.

⚠️ Compatibility

  • Minimum Obsidian version is now 1.13.0 (was 1.7.2) (#102). The settings tab is drawn as section pages with Obsidian's SettingPage, which exists from 1.13. The scanner reported that use against the old minimum, and the one-page tab kept for older versions called display(), which 1.13 deprecates. That tab is removed. Obsidian picks 0.7.4 for a vault on an older version, so nothing breaks there.

🔧 Under the Hood

  • The lint runs the scanner's rules (#102). npm run lint now builds on the recommended config of eslint-plugin-obsidianmd, which the community plugin scanner uses, instead of a hand-picked list of its rules, and fails on any warning. A finding the scanner would report now stops the commit.
  • The configuration guide drops the two screenshots of the one-page settings tab.
  • The test suite has 1,881 tests across 101 suites, all passing.

Full Changelog: https://github.com/akhmialeuski/obsidian-citation-extended/compare/0.7.4...0.7.5

README file from

Github

Obsidian Citation Extended

This plugin for Obsidian integrates your academic reference manager with the Obsidian editing experience.

Insert literature note link search modal listing references of a library

The plugin supports reading bibliographies in BibTeX / BibLaTeX .bib format, CSL-JSON format, Hayagriva YAML, directly from the Readwise API, and live from a running Zotero, either via the Better BibTeX pull-export endpoint or through Zotero's own local API (Zotero 7+, no extensions required).

Quick Start

  1. Install from Obsidian's Community Plugins browser
  2. Export your bibliography from Zotero + Better BibTeX, Mendeley, or Paperpile, or connect a running Zotero directly
  3. Add the database in Settings > Citation Extended
  4. Run Citation Extended: Open literature note from the Command Palette to search and open literature notes. No hotkeys are assigned by default, so bind one in Settings > Hotkeys if you use it often

For detailed setup instructions, see Getting Started.

Features

  • Open literature note: create or open a note for any reference
  • Insert literature note link: insert a wiki-link or markdown link
  • Insert literature note content: insert rendered template content at cursor
  • Insert markdown citation: insert Pandoc-style citations with presets (textcite, parencite)
  • Inline citation autocomplete: type @ or [@ to get a suggestion popover backed by the same fuzzy search index
  • References sidebar: a side panel listing every reference cited in the active note, with one-click navigation, Cmd/Ctrl-click to jump to a citation in the note, and "copy bibliography"
  • Zotero PDF annotation import: pull native Zotero highlights into templates as structured data (text, comment, color, page, tags) with zotero:// deep links that open the PDF at the exact annotation
  • Native Zotero connection: read a running Zotero (7+) through its built-in local API, with no Better BibTeX, no export files, native citation keys, group libraries and collection scoping
  • Non-destructive note updates: re-sync literature notes with the library. The plugin owns only its {{#syncBlock}} callouts and template frontmatter keys, merges changes three-way (yours + the library's) against the last synced snapshot, and shows a diff review dialog on real conflicts. Your own content is never touched
  • Insert or replace with template output: select outdated text in a note (such as PDF links from before a new attachment), extract the template part that produced it, edit it or load a saved profile, preview the result, and replace only the selection. With nothing selected, insert the output at the cursor
  • Readwise integration: import highlights and documents from Readwise as citable entries
  • Refresh citation database: manually reload all sources

See Features for details.

Templates

Customize your notes using Handlebars templates with 25+ variables, 18+ helpers, and built-in citation style presets.

Multiple Databases

Load citations from multiple .bib, .json, or .yml files, the Readwise API and a running Zotero at the same time. Every search result shows the name of its database, and a citekey found in two databases is kept as two separate entries.

Two database cards, a Better CSL JSON file and a Better BibTeX file

See Data Sources and Configuration for details.

Documentation

Full documentation is in the docs/ directory.

Network Use

This plugin accesses the network only when you configure it to, and it never sends telemetry or analytics.

  • Readwise API (readwise.io): contacted only if you add a Readwise data source and supply your own API token, in order to fetch your highlights (v2) and documents (v3) as citable entries. If you set a sync interval, the plugin re-fetches from this endpoint on that schedule. Otherwise it fetches on demand. Your token is stored locally in plugin settings and sent only to Readwise for authentication.
  • Local Zotero (127.0.0.1:23119): contacted only if you add a database whose source is Zotero (Better BibTeX) or Zotero (local API). The first pulls the Better BibTeX export and, when "Import PDF annotations" is on, your PDF annotations via the Better BibTeX JSON-RPC endpoint. The second reads Zotero's built-in local API. This is loopback-only traffic to Zotero running on the same machine, and nothing crosses the network.
  • Documentation links (github.com): the settings screen links to the plugin's documentation. These open in your browser when you click them. The plugin makes no automatic requests to GitHub.

All bibliography parsing happens locally. Nothing leaves your vault unless you explicitly enable the Readwise integration above.

File and Clipboard Access

The plugin reads files outside your vault and lists the notes inside it only for the features below, and it writes nothing outside the vault.

  • Library files outside the vault: a database whose source is a file (Better CSL JSON, Better BibTeX or Hayagriva (YAML)) reads the path you enter, which may be absolute and outside the vault, through Node's file system on desktop. The plugin watches that one file and reloads the library when it changes.
  • Markdown notes in the vault: to find the literature note of a citekey, the plugin lists the vault's Markdown files and matches them by path, by file name in any folder, and, when Note identifier field is set, by that frontmatter field. It reads no note content for this beyond Obsidian's metadata cache.
  • Opening attachments: in the search of Open literature note, Shift+Tab hands the entry's PDF to your operating system as a file:// path, and Tab opens the entry in Zotero through a zotero:// link. Nothing is opened unless you press one of them.
  • Clipboard: the plugin only writes to the clipboard, when you press Copy bibliography in the References view or Copy all in the template variable list. It never reads the clipboard.

Development

npm run dev      # Watch mode
npm run build    # Production build
npm run lint     # ESLint
npm test         # Jest test suite

Before opening a pull request, run the CRAP gate. It runs the suite with coverage and fails when a function in src/ scores over 8 on CRAP (complexity squared times the cube of its uncovered share, plus complexity) unless crap-baseline.json already records it at that score or higher. Files Jest leaves out of the coverage report, such as src/worker.ts, are not scored, and the gate names them in its summary. It needs Node 22.18 or later, which runs the TypeScript of tools/crap-gate.ts directly.

npm run crap-gate

On a green run, npm run crap-gate -- --update-baseline records every function that got better, so the baseline only falls. The complexity, parameter and length limits it shares with ESLint are checked by npm run lint, with existing debt recorded in .eslint/suppressions.json. Once a recorded violation is fixed, prune it:

npx eslint --suppressions-location .eslint/suppressions.json --prune-suppressions src

See Architecture for the design of the plugin.

License

MIT License.

Support

If you find this plugin useful, consider buying me a coffee.