Zotero PDF Copier & Renamer

A powerful, lightweight, and restartless add-on for Zotero 7, 8, and 9 that lets you copy attached PDF documents from selected bibliography references into any folder on your computer. Copied PDFs are automatically renamed based on the paper's title (sanitized for safe OS filenames) and index-deduplicated.

Developed and designed with custom branding and a native graphical interface.

---

Developer Details

• Author: Md. Parvej Hossain
• Email: contact@parvej.me
• Plugin ID: zotero-pdf-copier-renamer@parvej.me
• Icon Artwork: copy_9376689.png

---

Key Features

• Direct Context Menu Access: Right-click on any selected items in the main library grid pane to start copying instantly.
• Visual Icon Registration: Custom branded icon next to the context menu command and inside the Zotero Extensions listing for quick visual recognition.
• Smart PDF Copying: Filters all selected items to only copy actual PDF files (skips notes, web links, or citations that do not have attachments).
• Auto-Renaming by Title: Uses the parent paper's metadata title (e.g. Prediction of Track of Super Cyclone Amphan using WRF-ARW Model.pdf) instead of cryptic random hashes.
• Full Filename Sanitization: Automatically strips characters that are illegal or reserved in operating system path strings (such as :, ?, /, \, *, |, ", <, >).
• Smart Index Deduplication:
  • If a paper reference contains multiple PDF attachments, the copier appends numbered suffixes (e.g. Paper Title_(1).pdf, Paper Title_(2).pdf).
  • If a file with the same name already exists in the target destination folder, the copier automatically adds a sequence suffix to prevent overwriting existing work.
• Native OS Folder Picker: Directly launches the native operating system folder selection dialog (handling modern window.browsingContext requirements on Zotero 9/Gecko 128+).
• Graphical Progress Interface: Features Zotero's native ItemProgress layout showing an animated progress bar, real-time completion percentage, and the current file being copied.
• Auto-Close Timers: Automatically closes the notification card 5 seconds after copying is complete. Includes clickable dismiss control (click anywhere on the notification card to close immediately).

---

File Architecture

• manifest.json: Describes metadata and specifies Zotero 7 through Zotero 9 compatibility limits.
• package.json: Configures compilation parameters, dependencies, and packaging configurations.
• zotero-plugin.config.ts: Builds and bundles the typescript source code utilizing target firefox115.
• build.cjs: A clean, CommonJS Node.js script that compiles typescript assets using zotero-plugin build and packages them into the final zotero-pdf-copier-renamer.xpi installer archive.
• addon/: Folder containing the extension's static assets, resources, preferences, and chrome loaders.
• src/: Folder containing the TypeScript source code. Core operations are implemented in src/hooks.ts.

---

Compilation & Building

To package the extension from source:

1. Install Prerequisites: Ensure you have Node.js and npm installed on your machine.
2. Install Dependencies: Open a terminal in this directory and run:

   npm install
   

3. Compile and Package: Run the CommonJS builder script:

   node build.cjs
   

   This compiles the source code and generates the installer file zotero-pdf-copier-renamer.xpi in the project root.

---

Installation Guide

1. Open Zotero on your computer.
2. Go to the top menu: Tools -> Add-ons (or Extensions).
3. Click the gear icon (⚙️) in the top-right corner of the Add-ons manager page.
4. Select Install Add-on From File....
5. Select the generated zotero-pdf-copier-renamer.xpi file.
6. Click Install and restart Zotero when prompted.

---

How to Operate

1. Select one or more papers (regular references) in your Zotero library grid.
2. Right-click, and click Copy Attachments to Folder... (identified by the custom logo icon).
3. Select the destination folder on your laptop.
4. Watch the progress window in the bottom-right corner complete, and check your folder for the copied files!