{"id":20618601,"url":"https://github.com/allanchain/zotero-arxiv-workflow","last_synced_at":"2026-02-02T04:30:34.484Z","repository":{"id":238310503,"uuid":"796128902","full_name":"AllanChain/zotero-arxiv-workflow","owner":"AllanChain","description":"Helper for managing arXiv papers in Zotero","archived":false,"fork":false,"pushed_at":"2025-03-21T00:57:29.000Z","size":258,"stargazers_count":173,"open_issues_count":5,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T02:02:30.074Z","etag":null,"topics":["arxiv","zotero","zotero-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AllanChain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-05T02:43:47.000Z","updated_at":"2025-03-23T10:39:30.000Z","dependencies_parsed_at":"2024-05-18T03:27:41.727Z","dependency_job_id":"9aeb631c-4aa3-4961-8507-13bd524181d9","html_url":"https://github.com/AllanChain/zotero-arxiv-workflow","commit_stats":null,"previous_names":["allanchain/zotero-arxiv-workflow"],"tags_count":20,"template":false,"template_full_name":"windingwind/zotero-plugin-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllanChain%2Fzotero-arxiv-workflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllanChain%2Fzotero-arxiv-workflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllanChain%2Fzotero-arxiv-workflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllanChain%2Fzotero-arxiv-workflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AllanChain","download_url":"https://codeload.github.com/AllanChain/zotero-arxiv-workflow/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280190,"owners_count":20912966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arxiv","zotero","zotero-plugin"],"created_at":"2024-11-16T12:09:00.124Z","updated_at":"2026-02-02T04:30:34.478Z","avatar_url":"https://github.com/AllanChain.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"./addon/content/icons/favicon.svg\" width=\"200\"\u003e\u003c/p\u003e\n\u003ch1 align=\"center\"\u003earXiv Workflow for Zotero\u003c/h1\u003e\n\u003cp align=center\u003e\n  \u003ca href=\"https://github.com/AllanChain/zotero-arxiv-workflow/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/AllanChain/zotero-arxiv-workflow\" alt=\"GitHub release\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/windingwind/zotero-plugin-template\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Using-Zotero%20Plugin%20Template-blue?logo=github\" alt=\"Using Zotero Plugin Template\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/AllanChain/zotero-arxiv-workflow/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/downloads/AllanChain/zotero-arxiv-workflow/zotero-arxiv-workflow.xpi?logo=zotero\u0026logoColor=%23CC2936\" alt=\"total downloads\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nThis Zotero plugin addresses the pain when you store papers from arXiv and want to update your Zotero entry when they are published.\n\n\u003e [!Warning]\n\u003e This plugin is in alpha stage and only suports Zotero 7!\n\u003e\n\u003e I strongly recommend you to check the results manually after operations.\n\n## ✨ Features\n\n- 🪢 Merge a preprint item and a journal article item without pain\n- 🗃️ Easy to set which PDF to open by default\n- 📄 Search online if a arXiv paper is published or updated and update the information and PDF accordingly\n- 🌐 Download the latest version of published PDF\n\n## 🤔 Why?\n\nEasier workflow with arXiv paper!\n\n- The Zotero built-in merging feature does not support merging items of different type, therefore an arXiv paper and a journal article cannot merge.\n- I need the journal information from the journal item, while keeping the ID the same as the arXiv one. Because many plugins store data based on item ID, and I do not want to lose them.\n\n## 🪐 How?\n\nThis plugin focusing on the following workflow:\n\n- One parent item for both arXiv and published version.\n  - Keeping both items and relating them is also possible in Zotero, but not the focus of this plugin.\n- Item ID from the preprint item is used.\n  - Some plugins store data based on item ID.\n- Metadata from the published version is used.\n  - Usually, only the metadata of the publish version is needed to cite.\n  - However, something like the creation date follows the preprint item.\n  - The URL for the preprint is kept in the snapshot or web link attachment.\n- PDFs from both versions are kept.\n  - In case there are some annotations on the preprint PDF.\n  - And it is configurable which PDF to open by default.\n\nThe main logic of the merging process is demonstrated by the following plot:\n\n```\nBefore:                                     After:\n====================                        ====================\nItemID A (preprint)                         ItemID B\n--------------------                        --------------------\nMetadata A:                                 Metadata A:\nDate added (A)                              Date added (B)\nURL (A)                                     URL (B)\n...                                         ...\n--------------------               \\        --------------------\nPDF attachment a*         ----------\\       PDF attachment a*\n...                       ----------/       PDF attachment b\n====================               /        Web Link attachment\nItemID B (published)                        ...\n--------------------                        ====================\nMetadata B\nDate added (B)                              * means prefered PDF\nURL (B)\n...\n--------------------\nPDF attachment b*\n...\n====================\n```\n\n## 📸 Screenshots\n\n|          Merge arXiv           |          Prefer PDF           |\n| :----------------------------: | :---------------------------: |\n| ![Screenshot of merge arXiv][] | ![Screenshot of prefer PDF][] |\n\n[Screenshot of merge arXiv]: https://github.com/AllanChain/zotero-arxiv-workflow/assets/36528777/ebd7bb02-9caf-4e32-8f42-2afa7f119354\n[Screenshot of prefer PDF]: https://github.com/AllanChain/zotero-arxiv-workflow/assets/36528777/fe0dc757-6dbe-4d8b-894c-f806644686c7\n\n## 🔧 Installation\n\nDownload `zotero-arxiv-workflow.xpi` from the [release page](https://github.com/AllanChain/zotero-arxiv-workflow/releases). Firefox users need to right-click on the link and use \"Save link as\" instead of direct downloading it. After downloading, click \"Tools\" \u003e \"Plugins\" in Zotero menu and drag the downloaded file into the dialog.\n\n## 🎈 Explanation of each feature\n\nFeatures can be disabled from the plugin settings, but this will not affect the JavaScript API.\n\n### 🪢 Merge arXiv paper and the published one\n\nThe main logic of merging items is described [above](#-how). A few points to emphasis:\n\n- Select and only select two items: an arXiv paper and its published version.\n  - Do NOT select anything else, including any attachments of an item.\n- An item is considered published if it has type \"Journal Article\" or \"Conference Paper\".\n- The item for published version is deleted and the item for arXiv version will have updated info and attachments.\n- If the titles of these two items are different, a dialog will popup to ask user confirmation.\n\n\u003cdetails\u003e\n\u003csummary\u003eJavaScript API\u003c/summary\u003e\n\n```typescript\nasync Zotero.arXivWorkflow.api.merge(\n  preprintItem: Zotero.Item,\n  publishedItem: Zotero.Item,\n  suppressWarn = false,\n)\n```\n\nThis function assumes that the first argument is an arXiv version and the second is the published one. Currently, no checks will be performed to ensure this. The function caller is responsible to make sure the `type` of items is correct.\n\nIf `suppressWarn` is `true`, no confirmation dialog will popup if the title of two items are different.\n\n\u003c/details\u003e\n\n### 🗃️ Prefer to open a specific PDF\n\nMaybe you have merged some items manually before. Or maybe you just want to change the default PDF to open.\nEither case, you will find the \"Prefer PDF\" feature useful.\nTo use this feature, select (and only select) the PDF you want to open by default, right click, and select \"Prefer this PDF\".\n\n\u003cdetails\u003e\n\u003csummary\u003e\nUnder the hood, this plugin does something \"dirty\".\n\u003c/summary\u003e\n\nThat is because Zotero does not have the functionality of setting the default PDF to open.\nIt determines the PDF to open by checking and sorting by:\n\n- The attachment is a PDF\n- The URL field of the PDF matches the URL of the parent item\n- `dateAdded` of the PDF\n\nOr in SQL:\n\n```sql\nORDER BY contentType='application/pdf' DESC, url=? DESC, dateAdded ASC\n```\n\nTherefore, to make Zotero perfer a specific PDF, this plugin\n\n1. sets URL field of the PDF attachment the same as that of parent item\n2. sets the `dateAdded` field to be the oldest among all PDFs of parent item\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eJavaScript API\u003c/summary\u003e\n\n```typescript\nasync Zotero.arXivWorkflow.api.preferPDF(\n  selectedAttachment: Zotero.Item\n)\n```\n\nThis function assumes that the argument is a PDF attachment. Currently, no checks will be performed to ensure this. The function caller is responsible to perform the checks.\n\n\u003c/details\u003e\n\n### 📄 Search for updated version of an arXiv paper\n\nIf you have a preprint item for the arXiv paper, and you want to find if it has been published on journals or updated on arXiv, and then update the information, you can right click on the preprint item and select \"Update arXiv paper\". This will search:\n\n1. Published versions by trying:\n   1. [arXiv](https://arxiv.org) for the \"Related DOI\" field, which may be updated if the paper got published\n   2. [Semantic Scholar](https://www.semanticscholar.org) API\n   3. [DBLP](https://dblp.org) API\n2. If no published version found, the plugin will search [arXiv](https://arxiv.org) for updated versions\n\n\u003e [!Note]\n\u003e\n\u003e It is not trivial to correctly find the published version. If it fails, you'd better add the journal article item manually and use the merge feature this plugin provides.\n\nIf a published version is found, a new item will be created automatically and the published PDF will be downloaded. If you do not have access to the journal PDFs, you can disable downloading PDF from settings, and just update the metadata.\nAfter that, the preprint item and the newly created journal item will be merged with the same logic as mentioned earlier.\n\n\u003cdetails\u003e\n\u003csummary\u003eJavaScript API\u003c/summary\u003e\n\n```typescript\nasync Zotero.arXivWorkflow.api.arXivUpdate(\n  preprintItem: Zotero.Item\n)\n```\n\nThis function assumes that the argument is an arXiv item, and no checks will be performed to ensure this. The function caller is responsible to perform the checks.\n\n\u003c/details\u003e\n\n### 🌐 Download latest PDF\n\n\u003e [!Tip]\n\u003e\n\u003e This feature requires journal subscription.\n\nSay you have an arXiv paper PDF and import it into Zotero. Zotero finds that it has been published and uses the information from the published version. A few days later you might want to download the published version because it might be different from the arXiv one. With original Zotero, you have to open the journal URL, download the PDF, and add it as an attachment. With this plugin, it is as easy as right click and select \"Download latest PDF\".\n\n\u003cdetails\u003e\n\u003csummary\u003eJavaScript API\u003c/summary\u003e\n\n```typescript\nasync Zotero.arXivWorkflow.api.updatePDF(\n  journalItem: Zotero.Item\n)\n```\n\nThis function assumes that the argument is an journal item, and no checks will be performed to ensure this. The function caller is responsible to perform the checks.\n\nUnder the hood, this just calls `Zotero.Attachments.addAvailableFile` and limits the download source to DOI only.\n\n\u003c/details\u003e\n\n## 💻 Development\n\nThis repo is created from the [Zotero plugin template](https://github.com/windingwind/zotero-plugin-template), please follow the [quick start guide](https://github.com/windingwind/zotero-plugin-template?tab=readme-ov-file#quick-start-guide).\n\nThe following resources are also helpful:\n\n- [Zotero 7 for Developers](https://www.zotero.org/support/dev/zotero_7_for_developers)\n- [Zotero Plugin Development](https://www.zotero.org/support/dev/client_coding/plugin_development)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallanchain%2Fzotero-arxiv-workflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallanchain%2Fzotero-arxiv-workflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallanchain%2Fzotero-arxiv-workflow/lists"}