zotero better notes - Moses Yebei

The Problem

Zotero's built-in note editor is basic. Researchers juggle notes, annotations, and PDFs across separate tools because Zotero itself cannot handle linked notes, templates, Markdown sync, or flexible export. Better Notes (BN) closes that gap by turning Zotero into the single workspace for the entire reading-to-writing pipeline.

What This Does

BN is a Zotero plugin that replaces the stock note editor with a full-featured one. It supports note linking (inbound/outbound relations), customizable note templates, two-way Markdown file sync, and export to Markdown, DOCX, PDF, and mind maps. It also adds an outline, context pane, and image viewer to the note workspace.

The core logic lives in src/ (124 files, mostly TypeScript), while the actual plugin payload is assembled in addon/ (227 files) — the XPI structure Zotero loads. The src/extras/convertWorker/main.ts entry point runs a background worker for format conversion; src/index.ts is the plugin's main entry.

How It Is Wired

Execution starts at src/index.ts, which registers the plugin with Zotero's lifecycle hooks. From there, control flows into the note editor and command modules, which call into the conversion worker (src/extras/convertWorker/main.ts) for export and import operations. The worker runs as a separate process, so heavy conversions do not block the Zotero UI.

The addon/chrome/content/ folder holds the HTML shells for the editor (exportNotes.xhtml), the bubble map (bubbleMap.html), and DOCX export (docxExport.html). The addon/bootstrap.js file is the XPI bootstrap that Zotero executes on install. The typings/ folder (8 files) gives TypeScript definitions for Zotero's API, which is what lets the source compile against an external host.

The widest blast radius sits in the note editor module under src/ — nearly every feature (linking, templates, sync, export) routes through it. Changing its data model affects all downstream features. The module graph shows a hub-and-spoke pattern with the editor at the center; there is no mapped cycle, but a change to the editor's state management will ripple through the entire feature set.

The wiring has not been fully mapped for this repository — no internal call graph or file-by-file responsibility block exists beyond what the structure shows.

How To Use It

Setup: Clone and install dependencies.

git clone https://github.com/moses-y/zotero-better-notes
cd zotero-better-notes
npm install

Build: The package.json defines the build scripts. Run npm run build to produce the .xpi file in the build/ directory. The .env.example file lists any required environment variables (likely Zotero plugin signing keys — the repo does not document them beyond the template).

Install: In Zotero, go to Tools > Plugins, click the gear icon, select Install Add-on from file, and pick the built .xpi.

Run: There is no standalone runtime — the plugin activates inside Zotero once installed. The README's quick start covers opening note tabs and using the editor.

Real-World Use

A researcher reads a paper in Zotero, highlights three key passages, then double-clicks the note item to open the BN tab. They press a template shortcut to auto-generate a structured summary from the annotations, link it to two related notes, and export the result to Markdown for their Obsidian vault. The two-way sync keeps the Zotero note and the Markdown file in lockstep.

Code Health & Issues

No measured static analysis has run for this repository yet. Structural observations from the file tree:

Low — Tests exist (20 files in test/) and CI is configured (.github/workflows/CI.yml), but there is no coverage report or test count in the README. Verify coverage before relying on the suite.
Low — The repo is a fork of windingwind/zotero-better-notes (8,111 stars) with zero stars and no topics. Verify against the upstream for recent fixes; the fork may lag.
Low — docs/ holds only 3 files, thin for a plugin this feature-dense. Expect to read source for non-obvious behavior.

The Bottom Line

This is a mature, feature-rich Zotero plugin that solves a real workflow problem — the upstream has 8,000+ stars for a reason. The fork adds nothing visible over upstream, so use it only if you need the exact state of this tree. For anyone building on it, the TypeScript source and Zotero typings make it approachable, but the editor-centric hub will make deep changes expensive.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

409 files

TypeScript154
CSS21
YAML9
JSON9
JavaScript8
HTML7

React

Module dependencies

The 10 most depended-upon modules of 159, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_utils_str["str"] n1_src_utils_prefs["prefs"] n2_src_utils_locale["locale"] n3_src_utils_hint["hint"] n4_src_utils_wait["wait"] n5_src_utils_note["note"] n6_src_utils_workspace["workspace"] n7_src_utils_editor["editor"] n8_src_utils_link["link"] n9_test_utils_global["global"] n7_src_utils_editor --> n5_src_utils_note n7_src_utils_editor --> n1_src_utils_prefs n7_src_utils_editor --> n8_src_utils_link n7_src_utils_editor --> n3_src_utils_hint n3_src_utils_hint --> n4_src_utils_wait n5_src_utils_note --> n7_src_utils_editor n5_src_utils_note --> n0_src_utils_str classDef cyc stroke:#ef4444,stroke-width:2px; class n5_src_utils_note,n6_src_utils_workspace,n7_src_utils_editor cyc;

Dependencies

12 of 69 declared dependencies are a major version behind. Resolved 69 of 69 against the registry.

Package	Declared	Latest	Behind
`@types/node`	^20.19.9	26.2.0	6 major
`diff`	^5.2.0	9.0.0	4 major
`@types/diff`	^5.2.3	8.0.0	3 major
`cross-env`	^7.0.3	10.1.0	3 major
`@typescript-eslint/eslint-plugin`	^6.21.0	8.67.0	2 major
`@typescript-eslint/parser`	^6.21.0	8.67.0	2 major
`concurrently`	^8.2.2	10.0.5	2 major
`eslint`	^8.57.1	10.8.1	2 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

apexskier/github-release-commenter@v1, actions-cool/issues-helper@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/CI.yml

git push

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/tgbot.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Install from the lockfile in CImedium

.github/workflows

npm install with a committed package-lock.json

A fresh resolution in CI means the tested dependency set is not the locked one, so the failure only appears after merge.

Fix: Use npm ci, yarn install --immutable, or pnpm install --frozen-lockfile.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium

addon/chrome/content/lib/js/dx.all.js

1 blobs over 5MB: dx.all.js 5.2MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/CI.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/CI.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.