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.

---

Detailed Description

Zotero PDF Copier & Renamer is a specialized, production-grade productivity add-on engineered specifically for academic researchers, students, and professionals who manage large volumes of scientific literature in Zotero 7, 8, and 9. While Zotero excels at indexing bibliographic metadata, retrieving files, and synchronizing collections across devices, extracting attachments for external sharing, archiving, or mobile reading has historically been a cumbersome chore. Attachment files are stored inside deeply nested, cryptically named directories within the local Zotero storage folder, making them nearly impossible to navigate manually.

This extension bridges that gap by providing a seamless, single-click utility that extracts PDF attachments directly from your selected library entries and copies them to any target directory on your computer, while dynamically renaming each file based on its official bibliographic title.

Why It Is Essential

1. Elimination of Cryptic Folder Names: By default, Zotero stores attachments in isolated folders named with random alphanumeric hashes (e.g., 8WHS8FK2). When you need to copy a group of papers to a flash drive, email them to a collaborator, or read them on a tablet, finding these files manually is incredibly tedious. This extension handles the heavy lifting, consolidating the PDFs into a single, clean directory of your choosing.
2. Metadata-Driven Renaming: Instead of keeping default, unhelpful filenames like fulltext.pdf or manuscript.pdf, the extension extracts the exact "Title" field from your Zotero reference entry. It then cleanses the text—removing illegal operating system path characters (like :, ?, /, \)—and renames the PDF to match the paper's title (e.g., Tropical Cyclone Simulations with WRF.pdf).
3. Collision & Suffix Handling: Scientific publications sometimes share identical titles, or a single reference entry may contain multiple PDF files (such as main articles, supplemental files, and preprints). To prevent files from overwriting each other, the extension automatically detects naming conflicts in your destination folder and appends index tags (e.g. Paper Title_(1).pdf), ensuring that no research data is ever lost.
4. Modern Zotero 9 Integration: Built directly on Zotero's modern bootstrapped architecture, this plugin integrates natively with the Zotero user interface. It features a custom context menu icon and utilizes an animated graphical progress bar (ItemProgress) that provides real-time percentage feedback during bulk copy operations. Once the transfer is complete, a double-redundant close timer automatically cleans up the UI after 5 seconds, maintaining a clutter-free workspace.

---

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!