# Zotero PDF Copier & Renamer
[](https://github.com/iu-parvej/Zotero-PDF-Copier-Renamer/releases/download/v1.0.0/zotero-pdf-copier-renamer.xpi)
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.
> [!IMPORTANT]
> **Instant Bulk Exporting**: This extension is built specifically to process **multiple references at once**. Select dozens or hundreds of papers, right-click, choose your folder, and all attached PDFs are renamed and saved in a split second. No manual clicks, no tedious per-file folder navigation, and no slow popup loops!
Developed and designed with custom branding and a native graphical interface.
---
## Screenshots & Preview
### 1. Seamless Context Menu Integration
Select your bibliography references, right-click, and select **Copy Attachments to Folder...** to begin the export:
### 2. Live Status & Copy Completion
A native popup notification tracks the copy operation and confirms when the files have been copied successfully:
### 3. Clean Zotero Add-ons Listing
The extension is fully integrated with Zotero's Add-ons manager, showing the custom icon, updated author info, homepage, and version metadata:
---
## Detailed Description
**Zotero PDF Copier & Renamer** is a professional-grade productivity extension built from the ground up for researchers, students, academics, and knowledge managers who utilize Zotero 7, 8, or 9 as their primary reference management system. While Zotero is incredibly powerful for cataloging reference metadata, fetching citation records, and organizing library items, extracting the actual PDF attachments for external use has always been a painful, friction-heavy process.
By default, Zotero abstracts files inside a local database storage system. Each PDF is hidden inside a separate, randomly generated alphanumeric directory (such as `Zotero/storage/3A8B9CDF/`). While this hashed architecture is crucial for Zotero's database integrity and synchronization stability, it makes the physical files completely inaccessible to users wishing to browse their papers locally. If you want to copy a set of papers to a USB drive, upload them to a shared cloud folder, email them to a colleague, or send them to an iPad/tablet for reading, you must open each folder manually or rely on clunky workarounds. Furthermore, Zotero's downloaded files are often named generically (like `fulltext.pdf`, `manuscript.pdf`, or abbreviated author names), stripping away the context of the research paper itself.
This addon solves these limitations elegantly by introducing a native right-click context menu option that allows users to instantly copy the PDF attachments of all selected items directly to any target folder on their computer. The files are not just copied; they are dynamically processed, sanitized, and renamed based on the actual paper titles stored in Zotero's database.
### Why It Is Essential
1. **Intelligent Metadata-Driven Renaming**:
Instead of keeping obscure or generic filenames, the extension reads the parent item's official title metadata dynamically. It reformats the file name to be clean, human-readable, and highly descriptive. For example, a file stored as `fulltext.pdf` inside `Zotero/storage/7J8KL9MN/` is copied and renamed to `A Deep Learning Approach to Climate Modeling.pdf`.
2. **Advanced Filename Sanitization**:
Different operating systems (Windows, macOS, and Linux) have different rules and reserved characters for filenames. To prevent errors and system crashes during copy operations, the addon features a robust sanitization engine. It automatically strips or replaces illegal characters—such as colons (`:`), question marks (`?`), backslashes (`\`), forward slashes (`/`), asterisks (`*`), vertical bars (`|`), quotation marks (`"`), and inequality brackets (`<`, `>`)—ensuring absolute file path compatibility across any filesystem (NTFS, APFS, ext4).
3. **Smart Collision & Multi-Attachment Resolution**:
In high-volume research, naming conflicts are inevitable. You might have multiple papers with identical titles, or a single bibliographic entry might have multiple associated PDF files (for instance, the main article, a supplemental figures document, and a pre-print version). The addon handles this seamlessly. If a file with the target name already exists in the destination folder, or if there are multiple PDFs attached to a single item, the plugin automatically appends a numeric suffix (e.g., `Deep Learning Approach_(1).pdf`, `Deep Learning Approach_(2).pdf`), preventing accidental data loss or file overwriting.
4. **Modern, Native UI & Smooth User Experience**:
Leveraging Zotero's native user interface libraries, the extension integrates seamlessly into the application window. When a copy operation begins, a clean, modern notification popup appears in the bottom-right corner of Zotero. It features a graphical, animated progress bar using Zotero's native `ItemProgress` layout. This displays the percentage of files copied, a detailed text indicator of the specific paper currently being processed, and a visual loader. Once the operation is complete, the modal stays open for 5 seconds to let you confirm success, and then closes itself automatically. Users can also dismiss it instantly by clicking a close button or clicking anywhere on the popup.
5. **Future-Proof Gecko Integration**:
Built on Zotero's bootstrapped architecture, the addon is fully compatible with Zotero 7, Zotero 8, and Zotero 9. It incorporates advanced API compatibility layers to handle changes in Mozilla's Gecko engine, specifically addressing Gecko 128+ file picker standards by using `window.browsingContext` fallback logic, ensuring a smooth, crash-free experience on all modern and future Zotero versions.
---
## Developer Details
- **Author**: Md. Parvej Hossain
- **Email**: [contact@parvej.me](mailto:contact@parvej.me)
- **Plugin ID**: `zotero-pdf-copier-renamer@parvej.me`
- **Icon Artwork**: `copy_9376689.png`
---
## Key Features
- **Fast Bulk Exporting**: Optimized for batch actions. Select multiple items (tens or hundreds of references) at once, and copy all their attached PDFs simultaneously in less than a second without clicking any manual folder pickers for each file or dealing with popup loops.
- **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:
```bash
npm install
```
3. **Compile and Package**: Run the CommonJS builder script:
```bash
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. **Download the Extension**: Click [here to download the latest `zotero-pdf-copier-renamer.xpi` release](https://github.com/iu-parvej/Zotero-PDF-Copier-Renamer/releases/download/v1.0.0/zotero-pdf-copier-renamer.xpi).
2. Open **Zotero** on your computer.
3. Go to the top menu: **Tools -> Add-ons** (or **Extensions**).
4. Click the gear icon (`⚙️`) in the top-right corner of the Add-ons manager page.
5. Select **Install Add-on From File...**.
6. Select the downloaded **`zotero-pdf-copier-renamer.xpi`** file.
7. 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!