parvej/Zotero-PDF-Copier-Renamer
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: update README with detailed description and download link
Some checks are pending
Release / create-release (push) Waiting to run
Details

Browse Source
This commit is contained in:
MD. PARVEJ HOSSAIN 2026-06-10 23:13:08 +06:00
parent 697920a374
commit 01a0056fc4
1 changed files with 25 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
README.md
View File

@ -10,16 +10,28 @@ 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.
**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.
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.
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. **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.
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.
---
@ -78,12 +90,13 @@ To package the extension from source:
## 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.
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.
---