Weavero

A Zotero 7 to 10-beta plugin that layers convenience features on top of the standard library and reader: clickable links in annotation comments and notes, a fast filter pane, bookmarks, related-item tools, a structured tabs menu, tab and window management, and extra items-tree columns. Everything is individually toggleable in Preferences.

Note

Your documents are safe. Weavero never writes to or modifies your PDF files or attachments on disk — there's no risk of corrupting your documents. It only layers UI on top of Zotero's standard views and keeps its own data (bookmarks, preferences) in separate files. Any feature you turn off is inert.

Warning

Weavero is under active development — please report anything that misbehaves (open an issue). A few things to know:

• Built on Zotero's internals, and on a beta. Weavero hooks deep into Zotero's reader, items tree, tabs menu, and preferences, and is developed and tested against Zotero 10.0-beta. A Zotero update (beta or stable) can temporarily break a feature until the plugin catches up.
• Bookmarks are local-only. The Bookmarks feature stores its data in <Zotero data dir>/weavero/bookmarks.json. Bookmarks are not synced across computers and are not included in Zotero's cloud backup — they won't appear on your other devices, and they're lost if you start a fresh profile or lose that folder. Back up your Zotero data directory if your bookmarks matter to you. (The Zotero developers have said they intend to add plugin-managed synced storage; Weavero will adopt it once it's available.)
• Some features need Zotero 10. A few rely on Zotero 10 APIs and may be unavailable or behave differently on Zotero 9.
• Experimental, opt-in features. Some features are off by default and marked experimental in Preferences (e.g. PDF outline text highlight in the Extras tab) — they may be rough or change.

Features at a glance

Grouped the same way as the Preferences tabs. Expand a group below for the details and screenshots.

• Enhanced links and relations — clickable links (URLs, zotero://, 17 optional app schemes) in comments and notes; inline or icon + popup, colour-coded, with markdown; copy zotero:// links for items / collections / searches / reader page / location / selection; Ctrl/Shift+click navigation through internal document links (into a split pane or a second window); related-item tools (Add Related…, chain badge, Open Related submenu, Related column, linked-library highlight).
• Filters — items-tree filter popup (annotation colour/type/comment, attachment & item type, Has DOI/URL/Related/Links/Weavero Outline, multi-select tag/publication/author/added-by/collection/search) with a removable chip bar; reader annotation filter; Selection Target tri-state; structured tabs menu with per-library and file-type filters.
• Bookmarks — library bookmarks (items / collections / searches / URLs) via a toolbar dropdown; document bookmarks (in-PDF positions, pages, selected text, annotations) in a reader-sidebar tab, foldered and draggable, with search + funnel filter and hover cards; auto-hide when empty.
• Reader outline — an editable Outline tab: rename entries, add your own (selected text, page anchors, pinned spots), reorder and nest by drag, switch between the document's original outline and your curated copy — and a current-section highlight that follows your reading position.
• Tabs and Windows — pinned tabs (Firefox-style, icon-only); named, colour-coded tab groups (collapse, drag-into, reopen, move between windows); tab sessions (save and switch whole workspaces); multi-select tabs; move or tear-off a reader tab to another window with no reload (scroll, zoom and selection preserved); multi-tab reader windows with their own tab strip and a Firefox-style + button; full drag-and-drop tab management in the "List all tabs" popup; reopen the last closed window/group; an item-details pane beside the reader in separate windows; and optional multiple main windows.
• Default attachment — choose which child an item opens: any attachment (PDF or not), a linked URL, or a child note. Stored as a tag, so the choice syncs and survives without the plugin.
• Extras — items-tree columns (annotation, related, tag counts); Added By for annotations with per-user colours; group-library tab glyph; Hide title bar (Firefox-style); Open in External Viewer; a searchable Plugins Manager with richer plugin cards; PDF outline text highlight (experimental).

Features

Enhanced links and relations

Clickable links in annotation comments across the items tree, right item pane, reader sidebar, in-PDF popup, link badges over annotation icons, and notes. Each surface is independently toggleable. Out of the box https://, http://, and zotero:// are recognised; seventeen extra schemes (mailto:, obsidian://, vscode://, slack://, notion://, …) can be toggled per-scheme.

• Two display modes:
  • Inline — URLs, markdown, and app links render directly in the comment; an icon opens a popup with the full formatted view when the row is clipped.
  • Icon & Popup — comments stay plain text; an icon next to each annotation opens the popup. Per-content-type sub-toggles for URLs / markdown / app-links.
• Three colour buckets so each kind of link reads at a glance: blue for http(s), orange for zotero://, purple for app-scheme links.
• Inline markdown — **bold**, *italic*, ~~strike~~, `code`, [label](url).
• App-link skip-confirm — optional opt-in that bypasses Firefox's "Allow this site to open the … link?" prompt.
• Right-click "Copy Link" on any rendered URL.

Copy zotero:// links (right-click menus). All are standard zotero://open / zotero://select links — they work without the plugin and from other apps.

• Items list — Copy Item Link (zotero://select/.../items/<key>; multi-select joins with newlines).
• Collections tree — Copy Collection Link / Copy Saved Search Link.
• Reader (right-click on the page) — Copy Link to This Page in a PDF (zotero://open/.../items/<key>?page=N, N = the page you clicked, even in spread / continuous-scroll layouts), or Copy Link to This Location in an EPUB / web snapshot (?cfi=… / ?sel=… for the element under the cursor). With text selected it becomes Copy Link to Selected Text — for EPUB / snapshots that's a ?cfi=/?sel= link to the exact passage; for PDFs it stays page-level (no ?rects= URL form exists yet — zotero/zotero#4508).
• The zotero:// URI handler also resolves …/collections/<key> and …/searches/<key> paths (group-library variants supported), ?cfi= / ?sel= location params, and …/items?itemKey=K1,K2 multi-select, and switches focus to the library tab when followed from a note.

Interlinked navigation

Ctrl/Cmd-click or Shift+click an internal link to follow it without losing your place. Internal links include PDF cross-references and citations, EPUB section links, and web-snapshot #fragment links (external http(s) links are left alone).

• Ctrl/Cmd+click → split pane — opens (or reuses) a split and sends the target to the other pane, so the pane you clicked from stays put; a reverse Ctrl+click from the second pane drives the first. Split orientation (horizontal / vertical) is configurable.
• Shift+click → duplicate window — opens (or reuses) a second reader window of the same document and sends the target there; the two windows stay coupled both ways — handy across monitors.
• The target is highlighted in place (no scroll-to-top, no flash); a page reference with no text region gets a brief red locator dot instead.

Built on Zotero's own reader (zotero/reader, AGPL-3.0); it implements an idea first raised in this 2022 forum request for interconnected split views and reader windows.

Related and linked items — features built around Zotero's related-items relations (dc:relation) and the linked-items mechanism.

• Add Related… in the items-list right-click menu — opens Zotero's select-items dialog and links the chosen items as dc:relation peers (multi-annotation aware).
• Chain badge on annotation rows that have related items; click it for a popup listing the relations.
• Open Related Item submenu in the reader's annotation context menu (Open in Reader / In New Window per related item).
• Related column (items tree, icon-only) — count of related items per row.
• Linked-libraries highlight — when an item is replicated across libraries (linked items), the row matching the displayed item's library gets an accent background in the item pane's Libraries and Collections section.

Filters

Filter popup — a toolbar funnel ▼ next to the search box opens a compact filter panel; an accent dot marks the button while any filter is active. Click a facet to include, Alt+click to exclude. Filtering stays interactive on multi-ten-thousand-item libraries — a filter applies as fast as or faster than Zotero's own quick-search narrows; measured timings for all 39 filter configurations, the native comparison, and the methodology are in bench/.

• Annotation colour, type, has-comment
• Attachment file type — PDF / EPUB / Snapshot / Image / Video / Web Link / Linked File / Other File
• Item Type (native menulist + icon-only chips for the types you use), plus Standalone Note and Standalone Attachment tiles
• Parent flags: Has DOI, Has URL, Has Abstract, Has Attachment File
• Attachment / annotation flags: Has Bookmarks (Weavero document bookmarks), Has Annotations, Item Note
• Cross-level: Has Tag, Has Related, Has Link (a URL in a comment or note) — each with an Apply to scope (parent / attachment / annotation)
• Multi-select search: Tag, Publication / Journal (exact match — case matters), Author / Creator, Added By (group libraries), Collection, Saved Search; ranked matching (typing jfm finds Journal of Fluid Mechanics) with keyboard navigation (↑/↓ + Enter), and selections shown as include/exclude pills like Zotero's tag selector
• Selection Target: Parent / Attachment / Annotation tri-state — controls Ctrl+A scope and dims out-of-scope rows
• Strict per-row matching: OR across groups, AND within a group; filtering keeps only rows that match — ancestors are kept for tree shape, descendants are not auto-pulled.

Active filters show as a chip bar above the items tree — one removable chip each, plus + Filter, + OR Group, and Clear all. A chevron on a container's first visible child reveals rows the filter hid, and a scope button inside the search box can restrict quick-search to chosen row kinds.

See Filtering rules for the full logic.

Reader annotation filter. A funnel ▼ in the PDF / EPUB reader toolbar (next to Find) filters the open document's annotations by type, colour, has-comment, tags, and author — matched-out annotations disappear from both the sidebar list and the page, and it works even with the sidebar collapsed. Alt+click a chip to exclude; an accent dot marks the funnel while filtering, and a hide all annotations checkbox is included.

Tabs menu. The "List all tabs" dropdown gets a structured layout:

• Library grouping — section headers (themed library icon + name + tab count); the Library tab stays above all sections.
• Per-library tickbox filter — click to include, Alt+click to exclude. Hidden tabs disappear from the popup and from the main tab strip; the toolbar tabs-menu button picks up an accent tint while any filter is active.
• File-type filter (funnel button) — same theme-aware attachment icons as the items-tree filter (PDF / EPUB / Snapshot / Image / Video / Web Link / Other File), plus a yellow Note tile.
• Settings (gear button) — Sort by Library and Show Annotations Count toggles.

 

Bookmarks

Bookmarks across two scopes. Stored locally in <Zotero data dir>/weavero/bookmarks.json — see the syncing/backup warning near the top of this page.

• Library bookmarks — a Bookmarks dropdown on the collections-pane toolbar for items, collections, saved searches, whole libraries, and plain URLs. Right-click a collection or library in the tree for Bookmark Collection / Bookmark Library. Quick access to the things you return to.
• Document bookmarks — a Bookmarks tab in the reader sidebar for in-document locations: a precise position (drops a 📌 pin you can drag to re-place), a whole page (PDF), a selected-text passage, or an annotation in the current document — plus an "Elsewhere in Zotero" section for items / collections / URLs and cross-document selections. Add them from the + button or the reader's right-click menu.
• Library-bookmarks tab in the reader (optional) — also browse your Library-scope bookmarks from the reader's Bookmarks panel; a scope toggle switches between this document and library (Ctrl-click to show both).
• Folders & drag-and-drop — organise either list into folders and subfolders; reorder, nest (folders spring open on hover), and drag annotations, text selections, or items / collections / searches / libraries straight in.
• Search & filter — each list has a search field and a funnel that filters by annotation type / colour / tags / author.
• Rename, edit & reset — rename a bookmark (and edit its comment) without touching the source; Reset to Original Name restores the live label. Deleted targets show as dimmed, struck-through orphans with a ⚠ badge.
• Hover card — hovering a row shows a rich card: kind, colour swatch, page label, text preview, comment, tags, source document, and created date.
• Auto-hide when empty (optional, per scope) — hide the collections-pane button / reader tab until you add the first bookmark.

Reader outline

The reader's Outline tab becomes editable. Your edits are stored locally in <Zotero data dir>/weavero/outlines.json — see the syncing/backup warning near the top of this page; the document's own outline is never modified.

Works in PDFs, EPUBs and web snapshots: an EPUB's outline is its table of contents (scrolled and paginated layouts), a snapshot's is built from the page's headings.

• Sources — the document's embedded outline, the one Zotero extracts when a PDF has none, or your own Weavero outline (a curated copy, created on the first edit). A chip in the panel header switches between them. To start over, right-click the chip while the Weavero outline is shown, or the Weavero row of the chip's menu → Delete Weavero Outline… (asks for confirmation first; the document's own outline is not changed).
• Edit — rename entries (the target stays put, so renaming never changes where an entry goes), delete, reorder and re-indent by drag, expand/collapse all with + / -.
• Add your own entries — from selected text, a page anchor (top or bottom of a page), or a pinned spot you place in the document. Each kind carries its own glyph, and entries show their page number — something Zotero's own outline doesn't (zotero/zotero#3752). Don't want the page numbers? Right-click the Outline tab to hide them for that document, or turn them off for all documents in Preferences.
• Current-section highlight — as you scroll, the entry for the section you're reading is marked. It works on all three sources, and on entries you added yourself. The tree is never expanded or collapsed for you: the marker sits on the deepest entry visible in your tree, and relocates the moment you expand a branch. Zotero's own reader has highlighting since 7.0.11; Weavero's Outline tab replaces the native view, so it brings its own — plus the immediate refresh after expanding that the native one still lacks (forums #114157).
• …and it follows sections within a page. Native tracking is page-granular — several headings on one page are indistinguishable, in Zotero as in Acrobat and Firefox's viewer. Weavero compares your reading position (a quarter down the view, the same place a click on an entry lands its target) against each heading's own height, so a page of short sections is followed one heading at a time. Where a PDF's embedded outline stores no real heading coordinates — some store only a page — that page falls back to the page-granular behaviour.
• Reading Mode — the outline stays available as a read-only lens, and Reading Mode's own generated outline is offered as an extra source.

Tabs and Windows

Tab and window management on top of Zotero's tab bar. Each piece is individually toggleable.

• Pinned tabs — drag a tab into the pinned region (or Pin Tab in the tab right-click menu) for a Firefox-style, icon-only tab. Pins persist across restarts, never scroll out of view when the tab strip overflows, and clear automatically if the item is deleted.
• Tab groups — named, colour-coded groups on the tab bar: click to collapse/expand, hover to preview, right-click to rename, recolour, ungroup or close. Add tabs with the Add Tab to Group ▸ submenu or by dragging; saved groups can be reopened from the "List all tabs" dropdown. Groups move between windows as a whole: drag the group's chip onto any other main or reader window (released anywhere on the target window) and every member travels with it; drag it onto the desktop to pop the group into its own new window.
• Tab sessions — save the current workspace (every window and its tabs) as a named session and switch between sessions from the "List all tabs" dropdown. Switching first snapshots the current workspace to a Last workspace (auto) safety net, so nothing is lost.
• Multi-select tabs — Ctrl/Cmd+click to toggle and Shift+click for a range, then move or close several tabs at once.
• Move / tear-off reader tabs between windows — drag a reader tab into another window, or use Move to New Window. For PDFs this is a no-reload move that preserves scroll position, zoom and text selection (other attachment types fall back to a reload); the tab keeps its identity.
• Multi-tab reader windows — a separate reader window gets its own tab strip: hold several documents and notes in one window, with a Firefox-style + button (opens Zotero's item picker to add a tab, sitting flush against the last tab) and its own "List all tabs" button. Reader windows and their tabs — including their groups — are restored on restart.
• Drag-and-drop in the "List all tabs" popup — reorder tabs, drag them between windows (main or reader) or into groups with a WYSIWYG drop preview, and drag a group's header row to move the whole group. Popup moves land in the background: the tab you're reading stays focused, and moved tabs arrive unloaded until you select them.
• Reopen closed window / group — Ctrl/Cmd+Shift+T, or the matching context-menu entry.
• Item pane in separate reader windows — a standalone reader window can show the same item-details pane as the main window (metadata, attachments, related, notes, tags, collections). Resizable, with the width remembered.
• Multiple main windows — open a new main window with Ctrl+N (⌘N on macOS) or File → New Main Window (the File menu of a reader window has it too; on Windows and Linux the hamburger menu carries the same three — New Tab…, New Reader Window…, New Main Window — as the File menu does); the items/attachment context menu also gains a "New Window" action to open the selected items in a fresh main window. Any collection, library or saved search opens in a new main window too: middle-click it, or right-click → Open in New Window (Shift+click and Ctrl+click keep Zotero's meaning: selecting several collections) — and the collection you were in stays put: a right-click opens the menu for the row under the pointer (a thin dashed outline marks it) without moving the selection or your items list — through the menu's action too, so a cancelled dialog leaves nothing changed, and a sub-collection you create or rename from that menu is outlined where it appears while you stay put (an empty collection is nothing to look at). One switch in Settings → Weavero → Tabs and Windows → Multiple main windows governs every route, Ctrl+N included. On Windows, Weavero also works around Zotero's occasional ghost of a context menu left on screen while a dialog opened from it is up.
• Advanced Search in a new window — Edit → Advanced Search in New Window, Shift+click or middle-click the Advanced Search funnel (Shift+click works on Edit → Advanced Search too), or right-click the funnel → Open in New Window. A second main window opens on your whole library with Advanced Search already open, so the first window keeps showing what you were looking at — at a modest size rather than the main window's (it remembers the size you give it), like the separate Advanced Search window of Zotero 9, and without the collections and item panes — the search and its results (a setting brings the panes back). Zotero's own shortcut, Ctrl+Shift+F (⇧⌘F), does it too — the old separate-window reflex, back (a switch under Settings → Weavero → Tabs and Windows → Multiple main windows returns the shortcut to Zotero's in-window search). Zotero 10 only — Zotero 9's Advanced Search is already a separate window.

The "List all tabs" dropdown's library grouping and file-type filter live under Filters — that's the tabs menu; this group is tab management.

Default attachment

Zotero decides what a double-click opens with a fixed rule: PDFs first, then an attachment whose URL matches the item's, then the oldest. If your main paper sits next to a supplement, an accepted manuscript and a data file, that rule often picks the wrong one.

Right-click any child of an item → ▶️ Set as Default Attachment. The choice is not limited to PDFs — anything openable qualifies:

• file attachments, PDF and non-PDF (EPUB, HTML snapshot, image, …)
• linked URLs
• child notes

The same entry reads ▶️ Clear Default Attachment once set, so one menu item does both. (Zotero itself has a pending native Primary Attachment feature, zotero/zotero#3333; Weavero deliberately keeps the distinct Default name so the plugin tool and the future native feature stay tellable apart — and migrating from one to the other reads unambiguously. The problem's full history — a decade of upstream issues, the script lineage this feature descends from, and a critical audit of my own precursor script — is documented for review at default-attachment.) Turning the feature off in Settings → Weavero → Extras → Default attachment stops the override but keeps your picks.

How the choice is stored — and why it matters. The pick is an automatic tag, ▶️ wv-defatt, on the chosen child. That means it syncs to your other devices, it survives exporting, and it keeps working if you ever remove Weavero (the tag simply becomes an ordinary tag and Zotero returns to its own rule — nothing to repair). Deleting the child deletes the choice with it, so nothing is ever left dangling.

The leading ▶️ is rendered by Zotero in the items list, so a marked child is visible at a glance without spending one of your nine colour-tag slots.

Seeing what opens. The attachment that opens sits in the first row of an item's attachments (your chosen default, or Zotero's automatic pick when you haven't chosen), and the automatic pick carries a dimmed ▷ in the items list — so you can always see what would open if your chosen default were removed. All three behaviours have toggles in Settings → Weavero → Extras → Default attachment (on by default).

Finding every marked item: search wv-defatt, or the ▶️ glyph. The slug deliberately contains no ordinary words — searching default or attachment will not drag your marked items into unrelated results, which is exactly what a readable name would have done (Zotero's quick search matches substrings and splits on spaces).

Only one child per item is ever marked: setting a new default clears the previous one. Marking is not treated as editing the item, so Date Modified is left untouched — a sweep of choices won't scramble a Date Modified sort.

Coming from Default Attachment (PikaPei)

PikaPei/zotero-default-attachment does the PDF-only version of this. If Weavero finds picks saved by it, it asks what you want to do — it never imports them behind your back, because importing writes tags to your library and queues those items to sync:

Choice	What happens
Import into Weavero	Its picks become ▶️ wv-defatt tags. A choice you have already made in Weavero is never overwritten.
Don't import	Nothing is imported — for when you were only trying that plugin.
Keep using Default Attachment	Weavero's feature switches off and that plugin carries on exactly as before.

The third option appears only when that plugin is actually running. The question stays until you answer it: closing the window or ignoring it brings it back next start, rather than quietly deciding for you.

Weavero never writes to that plugin's data — on any path. Its preference is read-only to Weavero, so nothing you do here can damage it, and Keep using Default Attachment always leaves you exactly where you started. Changed your mind? Turn Weavero's feature back on in Settings → Weavero → Extras and the offer to import returns.

While Weavero's feature is on, that plugin's duplicate "Set Default" entry is hidden, so the menu offers one action rather than two that behave differently. Switch Weavero's feature off and its entry comes straight back.

Removing that plugin's leftover data (optional, manual). All of its state is a single preference, so there is nothing to uninstall beyond the plugin itself:

1. Settings → Advanced → Config Editor (this opens about:config).
2. Search for extensions.zotero.defaultattachment.mappings.
3. Delete / reset that preference.

That preference is the plugin's only copy of those choices — it is not synced and has no backup — so this cannot be undone. Your Weavero defaults are tags on the attachments and are not affected.

Being asked again. You are asked once, the first time Weavero finds anything — so installing Weavero before the other plugin is fine, its picks are still noticed when they appear. Once you have answered Import or Don't import, Weavero stops asking; that is deliberate, since a choice you cleared in Weavero would otherwise come back from the old plugin's data on every restart. (Keep using Default Attachment is not a final answer — the offer returns whenever you re-enable the feature.) If you kept making picks with that plugin afterwards, reset extensions.zotero.weavero.defaultChildMigrated in the same Config Editor to be asked once more.

Extras

Items-tree columns (icon-only, hidden by default; enable via the column-picker right-click on the items-tree header):

• Annotations — count of annotations on attachments; sums across attachments on regular items.
• Tags — count of tags per row: manual tags (blue) and automatic tags (default colour). Toggle off the automatic count to show only the manual count.
• Related — count of related items per row.

Group-library visuals:

• Added By for annotations — in group libraries, a badge showing who created each annotation (annotation rows aren't covered by Zotero's built-in Added By column), optionally tinted with a per-user colour so contributors are easy to scan.
• Group-library tab glyph + tooltip — tabs whose item lives in a group library get a small "Group Libraries" cluster glyph on the file-type icon, plus a tooltip showing the tab title and a library icon + Library Name header.

Window and utility extras:

• Hide title bar (Firefox-style) — replace the title bar with a browser-style bar (menus move out of the way, press Alt to summon them; window buttons move into the tab strip). Per-window-type sub-toggles (main window / separate reader window / separate note window). Windows / Linux only; off by default.
• Open in External Viewer — a right-click item that launches an item's best attachment with the OS default application (below Show File in the items list and Show in Library in the tab menu). Works for any stored file; the entry's icon mirrors the attachment type. (Replaces the standalone "Open PDF for Zotero" plugin.)
• Collections pane toggle — a collapse / expand button at the window's top-left that stays put when the pane goes, the twin of the item pane's and the reader's; View → Layout → Collections Pane keeps working. The collections search box, once open, takes a line of its own at the pane's full width. One switch in Preferences → Weavero → Extras → Collections pane.
• Ctrl+F in a reader tab — with the focus in the item pane on the right, or anywhere on the window outside the reader itself, Ctrl+F opens the reader's find bar; Zotero's own binding only selects the library search box, which is hidden there. A note being edited in the context pane keeps its own Ctrl+F. Cascades from the Extras master.
• Side panes stop at their minimum width — dragging the edge of the collections pane, the item pane, the context pane of reader tabs or the item pane of reader windows stops at the narrowest width instead of snapping the pane shut; collapse them with their buttons or View → Layout. Off, every one of them snaps shut, as in Zotero. On by default, Preferences → Weavero → Extras → Collections pane.
• Plugins Manager extras — Tools → Plugins gains a search box that filters the installed plugins as you type (Ctrl+F focuses it, × clears it); every card shows author [GitHub owner] · version · last updated under the plugin name, in the same order as the detail view; the manager opens as a normal window (minimize and maximize work) laid out like the main window, with its menus in a top-right hamburger; Recent Updates stays visible and gets a time-frame dropdown on its heading (last day, 2, 7, 30 or 90 days, or all — Zotero's own list stops at 2 days and never says so), remembered across restarts; and the manager always reopens on the Plugins list, not on the view it was closed on. One switch in Preferences → Weavero → Extras → Plugins Manager.
• PDF outline text highlight (experimental, off by default) — clicking a PDF outline (table-of-contents) entry flashes the actual heading text, not just the page. It recovers the heading position for embedded outlines (which only store a target point) and uses it directly for outlines Zotero generates itself, painting the highlight in place and keeping the timing consistent on rapid clicks (working around zotero/zotero forums #122030). The same consistent highlight applies to text-selection bookmarks. Built on Zotero's open-source reader (AGPL-3.0): it reuses the reader's text-analyzer glyph data (getProcessedData / getPageData) and its in-place highlight + outline-navigation internals — see zotero/pdf.js@2ec80d8 "Implement text analyzer" (mrtcode, 2023-03-09; a direct commit — Zotero's pdf.js/reader forks don't use PRs) and zotero/reader → src/pdf/pdf-view.js. Weavero only adds the join — matching the outline's title text against those glyph positions to recover the heading box that Zotero leaves as a bare point for embedded TOCs (zotero/zotero#2285, #3752).

Install

1. Download the latest weavero.xpi from the Releases page.
2. In Zotero: Tools → Plugins → ⚙ → Install Plugin From File… → pick the XPI.
3. Restart Zotero if prompted.

Quick start

After installing, a few things to try:

1. Clickable links — add a URL to an annotation comment (or note); it becomes clickable wherever the comment shows. Tune the surfaces and display mode in Preferences → Enhanced Links and Relations.
2. Filter your library — click the ▼ next to the items-tree search box and pick an annotation colour, item type, tag, … (Alt+click a chip to exclude).
3. Bookmark something — enable Preferences → Bookmarks, then use the Bookmarks dropdown on the collections-pane toolbar (items / collections / searches) or the Bookmarks tab in the reader sidebar (in-document locations).
4. Tidy the tabs menu — open "List all tabs" to see library grouping and the per-library / file-type filters.

Every feature is opt-in/opt-out under Tools → Plugins → Weavero → Preferences.

Configure

Open Tools → Plugins → Weavero → Preferences. Features are grouped into tabs (Enhanced Links and Relations, Filters, Bookmarks, Extras) and individually toggleable; optional URL schemes and experimental features are off by default.

Build

Plugin source is TypeScript under src/. A Zotero plugin ships as a zip with a .xpi extension, but the source has to be bundled first:

npm install        # one-time
npm run build      # esbuild bundles src/ → .scaffold/build/weavero.xpi (+ update.json with the XPI's SHA512 hash)

(Through the pre-TypeScript releases there was also a no-Node manual-zip path — scripts/build.ps1 zipping src/* directly. That no longer applies now that src/ is TypeScript and needs bundling; use npm run build.)

Development

Developed with Claude and MCP Server Zotero Dev (hot-reload + privileged-context JS for fast iteration). The full workflow — and a from-scratch guide to building Zotero plugins with an AI agent — is documented at Developing Zotero plugins with AI.

The AI workflow itself is published in this repo: CLAUDE.md (project guidance, agent-agnostic — AGENTS.md points there), the step-by-step workflows in .claude/skills/, path-scoped conventions in .claude/rules/, and mechanical gates in .claude/hooks/. Start with .claude/README.md for how the pieces fit together and the learning loop that turns every bug into a regression guard plus a process improvement. Contributions made with an AI agent are welcome — the agent will pick these files up automatically; please test what it produces before opening a PR.

The Node toolchain (optional but recommended) provides:

npm install              # one-time setup
npm run typecheck        # tsc --noEmit, hard-gated to 0 errors
npm test                 # Mocha + Chai inside a temp-profile Zotero
npm run build            # build the XPI to .scaffold/build/
npm start                # hot-reload dev loop (auto-reload on src/ changes)
npm run release          # interactive: bump → tag → push (CI then publishes)

Tests run inside a separate Zotero instance against a temp profile — your primary library is unaffected. CI runs the same suite headlessly on every PR and on every push to main.

Build/test tooling is all devDependencies (nothing from npm ships in the XPI): typescript (the typecheck gate), zotero-plugin-scaffold (the esbuild-based bundler + XPI packer + temp-profile test runner behind npm run build / test / start / release), zotero-types (Zotero's TypeScript definitions), and mocha + chai (+ their @types).

Compatibility

• Zotero 7.0+ (declared strict_min_version: 7.0, strict_max_version: 10.*).
• Tested on Zotero 10.0-beta. Some features rely on Zotero 10 APIs and may be unavailable or behave differently on Zotero 9.

Support

Weavero is free and open source. If it saves you time, you can support its continued development:

• Sponsor on GitHub — one-time or monthly, no platform fee, and two clicks if you already have a GitHub account.
• Buy me a coffee on Ko-fi — a one-off tip, no account needed (card, Apple Pay, or Google Pay).

Contributions go mostly toward the AI coding assistants (like Claude) I use to build and maintain Weavero, plus testing and keeping pace with new Zotero releases. You're never obligated — but if Weavero saves you time, anything you can spare helps keep it free and moving. Thank you.

License

GNU Affero General Public License v3.0 — same license as Zotero itself.

Third-party assets

The in-document position-bookmark marker uses the pin-angle-fill glyph from Bootstrap Icons, MIT licensed. Full notice: THIRD-PARTY-NOTICES.md.