{"id":13601254,"url":"https://github.com/windingwind/zotero-actions-tags","last_synced_at":"2025-05-14T12:10:36.900Z","repository":{"id":38535975,"uuid":"320139914","full_name":"windingwind/zotero-actions-tags","owner":"windingwind","description":"Customize your Zotero workflow.","archived":false,"fork":false,"pushed_at":"2025-01-05T16:47:19.000Z","size":1823,"stargazers_count":2181,"open_issues_count":2,"forks_count":51,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-05-01T15:02:17.773Z","etag":null,"topics":["actions","addon","automation","plugin","tag","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/windingwind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":["windingwind"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["https://paypal.me/windingwind"]}},"created_at":"2020-12-10T02:45:15.000Z","updated_at":"2025-05-01T01:38:42.000Z","dependencies_parsed_at":"2023-10-27T06:24:07.986Z","dependency_job_id":"d7b540ea-6431-4aa6-8f55-5d055998a06a","html_url":"https://github.com/windingwind/zotero-actions-tags","commit_stats":{"total_commits":249,"total_committers":6,"mean_commits":41.5,"dds":0.3493975903614458,"last_synced_commit":"0002cfbf3ccfa7e220bd4a634d821dc4ccce1e23"},"previous_names":["windingwind/zotero-actions-tags","windingwind/zotero-tag"],"tags_count":94,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windingwind%2Fzotero-actions-tags","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windingwind%2Fzotero-actions-tags/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windingwind%2Fzotero-actions-tags/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windingwind%2Fzotero-actions-tags/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/windingwind","download_url":"https://codeload.github.com/windingwind/zotero-actions-tags/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129481,"owners_count":22019628,"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":["actions","addon","automation","plugin","tag","zotero","zotero-plugin"],"created_at":"2024-08-01T18:00:59.463Z","updated_at":"2025-05-14T12:10:36.863Z","avatar_url":"https://github.com/windingwind.png","language":"TypeScript","funding_links":["https://github.com/sponsors/windingwind","https://paypal.me/windingwind"],"categories":["Extensions","TypeScript","automation","⚙️ 科研工具"],"sub_categories":["Customization","Skill"],"readme":"# ![Actions and Tags for Zotero](addon/chrome/content/icons/favicon.png)Actions and Tags for Zotero\n\n[![zotero target version](https://img.shields.io/badge/Zotero-7-green?style=flat-square\u0026logo=zotero\u0026logoColor=CC2936)](https://www.zotero.org)\n[![Using Zotero Plugin Template](https://img.shields.io/badge/Using-Zotero%20Plugin%20Template-blue?style=flat-square\u0026logo=github)](https://github.com/windingwind/zotero-plugin-template)\n\n_Customize your Zotero workflow._\n\n\u003cimg width=\"800\" alt=\"image\" src=\"https://github.com/windingwind/zotero-actions-tags/assets/33902321/05aa4dc2-4782-4ddf-84ea-949de96820a7\"\u003e\n\n## 🧩 Outline\n\n[🧐 What is this?](#-what-is-this)\n\n[👋 Install](#-install)\n\n[😎 Quick start](#-quick-start)\n\n[🔍 Advanced usage](#-advanced-usage)\n\n[🔧 Development](#-development)\n\n[🔔 Disclaimer](#-disclaimer)\n\n[🔎 My Zotero Plugins](#-my-zotero-plugins)\n\n[💰 Sponsor Me](#-sponsor-me)\n\n[🫶 Sponsors](#-sponsors)\n\n## 🧐 What is this?\n\n_Actions \u0026 Tags_ (AT), also known as _Zotero Tag_, is a plugin for [Zotero](https://zotero.org).\n\nAT can help you:\n\n- Automatically tag items with our [actions](), triggered by Zotero events or user-defined shortcuts\n- Automate your workflow with custom scripts!\n  - [Replace tag](https://github.com/windingwind/zotero-actions-tags/discussions/113)\n  - [Copy item link](https://github.com/windingwind/zotero-actions-tags/discussions/115)\n  - [Auto-generate note when opening item](https://github.com/windingwind/zotero-actions-tags/discussions/108)\n  - [Auto-translate new items' title/abstract](https://github.com/windingwind/zotero-actions-tags/discussions/107)\n  - [Find out more →](https://github.com/windingwind/zotero-actions-tags/discussions/categories/action-scripts)\n\n## 👋 Install\n\n- Download the latest release (.xpi file) from:\n\n  - [Latest Stable](https://github.com/windingwind/zotero-actions-tags/releases/latest)\n  - [All Releases](https://github.com/windingwind/zotero-actions-tags/releases)\n\n  _Note_: If you're using Firefox as your browser, right click the xpi and select \"Save As..\"\n\n- In Zotero click \"Tools\" in the top menu bar and then click \"Addons\"\n- Go to the Extensions page and then click the gear icon in the top right.\n- Select Install Add-on from file.\n- Browse to where you downloaded the .xpi file and select it.\n- Restart Zotero, by clicking \"restart now\" in the extensions list where the plugin is now listed.\n\n## 😎 Quick start\n\nThis plugin is designed to be easy to use. Start in **1 minutes**!\n\n### Getting started with example: `unread`\n\nWe have prepared a simple example for you to get started. The example is called `unread`, which will tag the item with `unread` when you add it to the library (create, import, or from zotero-connector) and remove the tag when you close the item.\n\nSteps:\n\n- Have this plugin installed and download a paper into your Zotero client.\n- The newly added item is tagged with `/unread`!\n- Open the item and read it.\n- Close the item and the tag is removed!\n\n\u003e Don't know where to find the tag? Check the \"Tags\" tab in the right panel. See also [Zotero Doc:adding tags to items](https://www.zotero.org/support/collections_and_tags#adding_tags_to_items)\n\n### Create your own actions\n\nNow that you have learned how to use the example, you can create your own actions!\n\nSteps to open the list of actions:\n\n- Open the settings (aka. preferences) page of this plugin. See [Zotero Doc:preferences](https://www.zotero.org/support/preferences) for more details.\n- Click the \"Actions \u0026 Tags\" tab.\n\nNow you can see a list of actions.\n\nThe community contributed some useful actions via `custom script`. Take an example of `copy item link`, You can use it by:\n\n1. Create an action by clicking the \"+\" button. Set the operation to `customScript`, assign `shortcut` and `menu label`.\n\n\u003cimg width=\"300\" alt=\"image\" src=\"https://github.com/windingwind/zotero-actions-tags/assets/33902321/9c327c8a-46d0-416c-b21a-95d4d021c9ea\"\u003e\n\n2. Copy the script from community: [[Share] Copy item link of the selected item](https://github.com/windingwind/zotero-actions-tags/discussions/115) -\u003e data.\n\n\u003cimg width=\"400\" alt=\"image\" src=\"https://github.com/windingwind/zotero-actions-tags/assets/33902321/fad3449a-13ac-4b13-bb19-efe537c4579d\"\u003e\n\n3. Paste the script to the `data` field of the action.\n\n4. Click \"Save\" to save the action.\n\nGreat! Now you can use the action by:\n\n- Right click the item in the library and select the action in the menu -\u003e trigger action -\u003e Copy item link.\n\n- Use the shortcut you assigned to the action.\n\nCheck your clipboard and you will find the link of the item!\n\nYou can find more actions by searching [community](https://github.com/windingwind/zotero-actions-tags/discussions/categories/action-scripts).\n\n### Action settings\n\nAn action has the following settings:\n\n- **Event**: The event that triggers the action.\n\n\u003cdetails style=\"text-indent: 4em\"\u003e\n\u003csummary\u003eShow supported events\u003c/summary\u003e\n\n| Event              | Description                                               |\n| ------------------ | --------------------------------------------------------- |\n| `createItem`       | Triggered when an item is created.                        |\n| `openFile`         | Triggered when an item is opened.                         |\n| `closeTab`         | Triggered when an item is closed.                         |\n| `createAnnotation` | Triggered when an annotation is created.                  |\n| `createNote`       | Triggered when a note is created.                         |\n| `appendAnnotation` | Triggered when an annotation is appended to target item.  |\n| `appendNote`       | Triggered when a note is appended to target item.         |\n| `programStartup`   | Triggered when the Zotero client (or this plugin) starts. |\n| `mainWindowLoad`   | Triggered when the main window is loaded.                 |\n| `mainWindowUnload` | Triggered when the main window is unloaded (closed).      |\n\n\u003c/details\u003e\n\n- **Operation**: The operation that the action will perform.\n\n\u003cdetails style=\"text-indent: 4em\"\u003e\n\u003csummary\u003eShow supported operations\u003c/summary\u003e\n\n| Operation      | Description                                                                    |\n| -------------- | ------------------------------------------------------------------------------ |\n| `addTag`       | Add tag(s) to the target item.                                                 |\n| `removeTag`    | Remove tag(s) from the target item.                                            |\n| `toggleTag`    | Add tag(s) to the target item if it doesn't have the tag, otherwise remove it. |\n| `otherAction`  | Run other custom actions.                                                      |\n| `customScript` | Run a custom script.                                                           |\n\n\u003c/details\u003e\n\n- **Data**: The action data.\n\n  - For tag operations, it's tags separated by comma\n  - For custom script, it's the script code.\n  - For trigger other actions, it's the target actions' names (each in one line).\n\n  \u003e Click `⤤` in the edit action popup to open editor for multi-line data.\n\n- **Shortcut**: The shortcut that triggers the action. Leave it empty if you don't want to use a shortcut.\n\n  \u003e Click shortcut button in the edit action popup to record custom shortcut from keyboard.\n\n- **Menu Label**: The label of the menu item to be displayed in the right-click menu in the library / reader popup menu.\n\n  \u003e Leave empty to hide in the menu.\n  \u003e Sort by the menu label alphabetically.\n\n  - Item Menu  \n    \u003cimg width=\"300\" alt=\"image\" src=\"https://github.com/windingwind/zotero-actions-tags/assets/33902321/c0b45172-82ec-450d-b578-0aeb2c33e7ea\"\u003e\n  - Collection Menu  \n    \u003cimg width=\"300\" alt=\"image\" src=\"https://github.com/windingwind/zotero-actions-tags/assets/33902321/90e8f705-8d51-4485-81d9-af927e850200\"\u003e\n  - Tools Menu\n  - Reader Menu  \n    \u003cimg width=\"300\" alt=\"image\" src=\"https://github.com/windingwind/zotero-actions-tags/assets/33902321/d7ccbb74-5344-4604-aa84-36f624761c00\"\u003e\n  - Annotation Menu  \n    \u003cimg width=\"300\" alt=\"image\" src=\"https://github.com/windingwind/zotero-actions-tags/assets/33902321/d1fa0cb9-4f40-46f7-bf75-9c1b19830955\"\u003e\n\n- **Enabled**: Whether the action is enabled. Uncheck it to disable the action.\n\n## 🔍 Advanced usage\n\n### Colorize your tags\n\nYou can colorize your tags by assigning a color to the tag in the tag selector. See [Zotero Doc:colored tags](https://www.zotero.org/support/collections_and_tags#colored_tags) for more details.\n\nUse cases:\n\n- Assign a color to the `/unread` tag so that you can easily find the unread items in your library.\n- Assign colors to the `⭐️`, `⭐️⭐️`, `⭐️⭐️⭐️`, ... tags so that you can easily sort the items by their importance.\n\n### Custom script\n\n\u003e ⚠️ **Warning**: Custom script is a powerful feature. It can do anything that you can do in the Zotero client. Use it with caution!\n\u003e\n\u003e All the scripts shared in the [community](https://github.com/windingwind/zotero-actions-tags/discussions/categories/action-scripts) will be manually reviewed by me to make sure it is not malicious. However, they may still cause data loss if you does not use them properly!\n\u003e Do not run the script that you do not trust!\n\nYou can run custom script with the `customScript` operation. The script will be executed in the context of the Zotero client.\n\nShare \u0026 find custom scripts here: https://github.com/windingwind/zotero-actions-tags/discussions/categories/action-scripts\n\nYou can use the following variables in the script:\n\n- `triggerType`: The trigger type. Can be `menu`, `shortcut`, `createItem`, `openFile`, `closeTab`, `createAnnotation`, `createNote`, `appendAnnotation`, `appendNote`, `programStartup`, `mainWindowLoad`, `mainWindowUnload`.\n\n- `item`: The target item. Might be `null` if the action is triggered by an event that doesn't have a target item, e.g. shortcut in the Zotero client without selecting an item. (Not available in `programStartup`, `mainWindowLoad`, and `mainWindowUnload` event)\n\n  \u003cdetails style=\"text-indent: 4em\"\u003e\n  \u003csummary\u003eExamples with `item`\u003c/summary\u003e\n\n  - Get the title of the item: `item.getField('title')`. More details of the available fields can be found in [Zotero:item fields](https://api.zotero.org/itemFields?pprint=1)\n  - Get the tags of the item: `item.getTags().map(tag =\u003e tag.tag)`\n  - Add a tag to the item: `item.addTag('tag')`\n  - Remove a tag from the item: `item.removeTag('tag')`\n\n  \u003c/details\u003e\n\n- `items`: The target items[] array. Only available in menu/shortcut-triggered actions, otherwise it's `null`.\n\n  When selecting multiple items in the library, the action will be triggered once for all items (`items=[...], item=undefined`) and then one by one for each item (`items=[], item=...`). You can use the `items` variable to get the selected items array and avoid duplicate executions.\n\n  \u003e Please always use the `items` instead of `ZoteroPane.getSelectedItems()`. The action can be triggered from entrances outside the library, where the items are not from `ZoteroPane`.\n\n  \u003cdetails style=\"text-indent: 4em\"\u003e\n  \u003csummary\u003eExamples with `items`\u003c/summary\u003e\n\n  ```js\n  if (item) {\n    // Disable the action if it's triggered for a single item to avoid duplicate operations\n    return;\n  }\n\n  if (items?.length \u003e 0) {\n    // Do something with all selected items\n  }\n  ```\n\n  \u003c/details\u003e\n\n- `collection`: The target collection object, is only available when triggered by the collection menu.\n\n- `require`: The `require` function to import global variables. Use `const window = require('window')` to import the `window` variable.\n\n  \u003cdetails style=\"text-indent: 4em\"\u003e\n  \u003csummary\u003eExamples with `require`\u003c/summary\u003e\n\n  - Get selected items: `const selectedItems = require('ZoteroPane').getSelectedItems()`\n  - Get the item of current tab:\n\n    ```js\n    const Zotero = require(\"Zotero\");\n    const Zotero_Tab = require(\"Zotero_Tab\");\n    const itemID = Zotero_Tabs._tabs[Zotero_Tabs.selectedIndex].data.itemID;\n    const item = Zotero.Items.get(itemID);\n    ```\n\n  \u003c/details\u003e\n\n- `window`: Only available in `mainWindowLoad` and `mainWindowUnload` event. In other events, you should use `require('Zotero').getMainWindow()` to import the `window` variable.\n\n## 🔧 Development\n\nThis plugin is built based on the [Zotero Plugin Template](https://github.com/windingwind/zotero-plugin-template). See the setup and debug details there.\n\nTo startup, run\n\n```bash\ngit clone https://github.com/windingwind/zotero-actions-tags.git\ncd zotero-actions-tags\nnpm install\nnpm run build\n```\n\nThe plugin is built to `./build/*.xpi`.\n\n## 🔔 Disclaimer\n\nUse this code under AGPL. No warranties are provided. Keep the laws of your locality in mind!\n\n## 🔎 My Zotero Plugins\n\n- [Better Notes for Zotero](https://github.com/windingwind/zotero-better-notes): Everything about note management. All in Zotero.\n- [Translate for Zotero](https://github.com/windingwind/zotero-pdf-translate/): Translate PDF, EPub, webpage, metadata, annotations, notes to the target language. Support 20+ translate services.\n\n## 💰 Sponsor Me\n\nI'm windingwind, an active Zotero(https://www.zotero.org) plugin developer. Devoting to making reading papers easier.\n\nSponsor me to buy a cup of coffee. I spend more than 24 hours every week coding, debugging, and replying to issues in my plugin repositories. The plugins are open-source and totally free.\n\nIf you sponsor more than $10 a month, you can list your name/logo here and have priority for feature requests/bug fixes!\n\n## 🙌 Sponsors\n\nThanks\n[peachgirl100](https://github.com/peachgirl100), [Juan Gimenez](),\nand other anonymous sponsors!\n\nIf you want to leave your name here, please email me or leave a message with the donation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwindingwind%2Fzotero-actions-tags","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwindingwind%2Fzotero-actions-tags","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwindingwind%2Fzotero-actions-tags/lists"}