79 lines
4.3 KiB
Markdown
79 lines
4.3 KiB
Markdown
# 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](mailto: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:
|
|
```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. 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!
|