{"id":13618354,"url":"https://github.com/dvanoni/notero","last_synced_at":"2025-12-30T02:26:47.391Z","repository":{"id":39901062,"uuid":"410689335","full_name":"dvanoni/notero","owner":"dvanoni","description":"A Zotero plugin for syncing items and notes into Notion","archived":false,"fork":false,"pushed_at":"2025-04-01T19:03:40.000Z","size":8579,"stargazers_count":2672,"open_issues_count":64,"forks_count":113,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-04-10T20:55:32.321Z","etag":null,"topics":["notion","notion-database","typescript","zotero","zotero-plugin","zotero-sync"],"latest_commit_sha":null,"homepage":"https://download.notero.vanoni.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dvanoni.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null},"funding":{"custom":"https://bmc.link/dvanoni"}},"created_at":"2021-09-26T23:54:44.000Z","updated_at":"2025-04-09T17:36:52.000Z","dependencies_parsed_at":"2023-09-22T13:25:59.839Z","dependency_job_id":"ead5cd76-29aa-42e7-a1ad-cc0ad833a1a6","html_url":"https://github.com/dvanoni/notero","commit_stats":{"total_commits":337,"total_committers":12,"mean_commits":"28.083333333333332","dds":"0.35608308605341243","last_synced_commit":"441ade93d22d428fa6608182304344fa24afe582"},"previous_names":[],"tags_count":57,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dvanoni%2Fnotero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dvanoni%2Fnotero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dvanoni%2Fnotero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dvanoni%2Fnotero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dvanoni","download_url":"https://codeload.github.com/dvanoni/notero/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059520,"owners_count":22007771,"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":["notion","notion-database","typescript","zotero","zotero-plugin","zotero-sync"],"created_at":"2024-08-01T20:01:59.388Z","updated_at":"2025-12-30T02:26:47.384Z","avatar_url":"https://github.com/dvanoni.png","language":"TypeScript","funding_links":["https://bmc.link/dvanoni","https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapp.buymeacoffee.com%2Fapi%2Fcreators%2Fslug%2Fdvanoni\u0026query=%24.data.public_supporters_count\u0026prefix=%F0%9F%92%9C%20\u0026style=social\u0026logo=buymeacoffee\u0026label=Buy%20me%20a%20coffee","https://www.buymeacoffee.com/dvanoni"],"categories":["TypeScript","Extensions","zotero-plugin"],"sub_categories":["Integrations"],"readme":"# Notero\n\n[![Latest release](https://img.shields.io/github/v/release/dvanoni/notero)](https://github.com/dvanoni/notero/releases/latest)\n[![Total downloads](https://img.shields.io/github/downloads/dvanoni/notero/latest/total?sort=semver)][download]\n[![Works with Zotero](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdvanoni%2Fnotero%2Fmain%2Fpackage.json\u0026query=%24.xpi.zoteroMinVersion\u0026prefix=v\u0026suffix=%2B\u0026logo=zotero\u0026label=Works%20with%20Zotero\u0026color=%23CC2936)](https://www.zotero.org/)\n[![Buy me a coffee](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapp.buymeacoffee.com%2Fapi%2Fcreators%2Fslug%2Fdvanoni\u0026query=%24.data.public_supporters_count\u0026prefix=%F0%9F%92%9C%20\u0026style=social\u0026logo=buymeacoffee\u0026label=Buy%20me%20a%20coffee)](https://www.buymeacoffee.com/dvanoni)\n\nNotero is a [Zotero plugin](https://www.zotero.org/support/plugins) for syncing\nitems and notes into [Notion](https://www.notion.so/product). To use it:\n\n1. 💾 [Install][] the Notero plugin into Zotero.\n2. 📔 [Connect][] and configure your Notion database.\n3. 📁 Choose your Zotero collections to monitor.\n4. 📝 Add or update items in your collections.\n5. 🔄 Watch your items sync into Notion!\n\n[Install]: #install-and-configure-notero-plugin\n[Connect]: #connect-to-notion\n\n![Notero in action](docs/notero.gif)\n\nConcept by [@arhoff](https://github.com/arhoff) 👩🏻‍🔬 |\nBuilt with 💜 by [@dvanoni](https://github.com/dvanoni)\n\n## Table of Contents\n\n- [Why Use Notero?](#why-use-notero)\n- [How Notero Works](#how-notero-works)\n- [Installation and Setup](#installation-and-setup)\n- [Usage Guides](#usage-guides)\n- [Frequently Asked Questions](#frequently-asked-questions)\n- [Example Notion Databases](#example-notion-databases)\n- [Development](#development)\n\n## Why Use Notero?\n\n- Integrate your reference manager, task list, reading notes, analytical tables,\n  and drafts in one location.\n- Easily link to references when writing in Notion.\n- Create custom views to filter and sort large reference lists by project,\n  tag, author, etc.\n- Backlinks make it easy to locate any of the notes and drafts that mention\n  a reference.\n- Link references to entries in other databases, such as projects, tasks,\n  manuscripts in your publication pipeline, publishing outlets, etc.\n\n## How Notero Works\n\nThe Notero plugin watches for Zotero items being added to or modified within\nany collections that you specify in the Notero preferences. Whenever an item\nis added or modified, Notero does a few things:\n\n- Save a page with the Zotero item's properties (title, authors, etc.) into the\n  Notion database specified in Notero preferences.\n- Add a `notion` tag to the Zotero item.\n- Add an attachment to the Zotero item that links to the page in Notion.\n\nIn addition to providing a convenient way to open a Notion page from Zotero,\nthe link attachment also serves as a reference for Notero so that it can update\nthe corresponding Notion page for a given Zotero item.\n\n### Syncing Items\n\nBy default, Notero will sync items in your monitored collections whenever they\nare modified. You can disable this functionality by unchecking the **Sync when\nitems are modified** option in the Notero preferences.\n\nYou can also sync items from the collection or item context menus (right-click):\n\n- To sync all items in a collection, open the context menu for the collection\n  and select **Sync Items to Notion**.\n- To sync one item or multiple items, select the item(s) in the main pane, open\n  the context menu, and select **Sync to Notion**.\n\n\u003e [!NOTE]\n\u003e To prevent the \"sync on modify\" functionality from saving to Notion multiple\n\u003e times, Notero does not notify Zotero when the tag and link attachment are\n\u003e added to an item. This means they may not appear in Zotero immediately, and\n\u003e you may need to navigate to a different item and back to make them appear.\n\n### Syncing Notes and PDF Annotations\n\nZotero notes associated with an item can be synced into Notion as content of the\ncorresponding page for that item. As with regular items, you can manually sync\nnotes using the **Sync to Notion** option in the context menu.\n\nAutomatic syncing of notes can be enabled via the **Sync notes** option in the\nNotero preferences. When enabled, notes will automatically sync whenever they\nare modified. Additionally, when a regular item is synced, all of its notes will\nalso sync if they have not already.\n\nTo sync annotations (notes and highlights) from a PDF, you'll first need to\nextract them into a Zotero note:\n\n1. Select an item or PDF, open the context menu, and select\n   **Add Note from Annotations**.\n2. If desired, enable highlight colors from the menu at the top-right of the\n   note panel.\n\n\u003cdetails\u003e\n  \u003csummary\u003eExample of creating a note from PDF annotations\u003c/summary\u003e\n  \u003cvideo src=\"https://github.com/dvanoni/notero/assets/299357/4cda5dc7-ba5b-4f5a-8f53-d6bc2c44b1dc\" /\u003e\n\u003c/details\u003e\n\n## Installation and Setup\n\nUsing Notero involves installing the plugin in Zotero and connecting it to a\nNotion database. Detailed setup instructions are below.\n\n### Install and Configure Notero Plugin\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e - The latest release of Notero requires Zotero 7.0 or above.\n\u003e - Support for Zotero 6.0.27 and above is available in Notero [v0.5.17][].\n\u003e - See the [changelog](CHANGELOG.md) for all release notes.\n\n1. [Download][] the latest release of the `.xpi` file.\n   - Alternatively, download the `.xpi` file from the **Assets** section of the\n     [latest release][] page.\n   - Firefox users: Right-click the download link and choose **Save Link As...**\n     to download the file.\n2. Open the Zotero Plugins Manager via the **Tools → Plugins** menu item.\n3. Install the `.xpi` file by either:\n   - dragging and dropping it into the Plugins Manager window _or_\n   - selecting it using the **Install Plugin From File...** option in the\n     gear menu in the top-right corner of the window\n4. Open the Notero preferences from either the **Tools → Notero Preferences...**\n   menu item or the sidebar in the main Zotero preferences window.\n5. Configure the Notero preferences as desired.\n\n[download]: https://download.notero.vanoni.dev\n[latest release]: https://github.com/dvanoni/notero/releases/latest\n[v0.5.17]: https://github.com/dvanoni/notero/releases/tag/v0.5.17\n\n### Connect to Notion\n\n\u003e [!NOTE]\n\u003e\n\u003e Before version 1.0.0, Notero required you to create your own Notion internal\n\u003e integration and manually set the integration secret in the Notero preferences.\n\u003e This is no longer necessary as Notero now uses a public integration with an\n\u003e authentication flow provided by Notion.\n\u003e\n\u003e If you previously set up Notero with an internal integration, you can click\n\u003e the **Upgrade Connection** button in the Notero preferences to switch to the\n\u003e public integration as described below. Once complete, you can delete your\n\u003e internal integration from the [Notion integrations][] page.\n\n1. Start the Notion connection process by clicking the **Connect to Notion**\n   button in the Notero preferences. This will open the Notion connection page\n   in your default web browser.\n2. On the Notion connection page, select your desired workspace from the menu\n   at the top (if you have multiple). Then, click **Next**.\n3. On the next page, choose whether you want to use a template database or\n   connect to an existing database page.\n   - If you choose to use a template, the [basic example](#basic-example)\n     database will be duplicated into your workspace.\n   - If you choose to select an existing database, you can search for and select\n     your preferred database on the next page. You can also select no database\n     and connect one later in Notion.\n4. Click **Allow access** to give Notero access to your Notion workspace and\n   database. You will then be redirected to a page that prompts you to open\n   Zotero.\n5. Click **Open Zotero** to complete the connection process in Zotero. The\n   Notero preferences should show that you are connected to your Notion\n   workspace.\n   - If Zotero does not open or successfully connect to Notion, copy the\n     connection token from the Notion connection page and paste it into the\n     **Connection Token** field in Notero preferences.\n\n\u003cdetails\u003e\n  \u003csummary\u003eExample of connecting to Notion\u003c/summary\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/6c759c9d-f032-4060-bfd0-8da285ce0c2a\" /\u003e\n\u003c/details\u003e\n\n[Notion integrations]: https://www.notion.so/profile/integrations\n\n### Configure Notion Database\n\nIf you choose not to use the template database during the Notion connection\nprocess, you will need to create your own database. See\n[examples](#example-notion-databases) below that you can duplicate into\nyour workspace, or create one from scratch with properties described in the\n[database properties](#notion-database-properties) section below.\n\nTo give Notero access to your database, follow these steps:\n\n1. Go to the database page in your workspace.\n2. Click on the **•••** More menu in the top-right corner of the page.\n3. Scroll down to and click **Connections**.\n4. Search for and select **Notero** in the **Search for connections...** menu.\n\n\u003cdetails\u003e\n  \u003csummary\u003eExample of connecting database to Notero\u003c/summary\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/c4c25fbe-4d66-4985-a23f-1972762906a7\" /\u003e\n\u003c/details\u003e\n\n#### Notion Database Properties\n\nNotero can sync data for the properties listed below. The only property required\nby Notero is one with the **Title** property type. The other properties are\noptional, so you can use only the ones that suit your needs.\n\nThe **Title** property can be named something other than `Name` as long as it\ndoes not conflict with any of the other property names. The name and type of\nthe other properties must be configured exactly as specified here. Note that\nproperty names are case-sensitive, so the capitalization must match exactly.\n\nSupport for customizing properties is planned for the future;\nsee issue [#355](https://github.com/dvanoni/notero/issues/355).\n\n| Property Name       | Property Type | Notes                                                                          |\n| ------------------- | ------------- | ------------------------------------------------------------------------------ |\n| `Name`              | Title         | Format configurable via the **Notion Page Title** option in Notero preferences |\n| `Abstract`          | Text          |                                                                                |\n| `Authors`           | Text          |                                                                                |\n| `Citation Key`      | Text          | Requires [Better BibTeX](https://retorque.re/zotero-better-bibtex/)            |\n| `Collections`       | Multi-select  |                                                                                |\n| `Date`              | Text          |                                                                                |\n| `Date Added`        | Date          |                                                                                |\n| `Date Modified`     | Date          |                                                                                |\n| `DOI`               | URL           |                                                                                |\n| `Editors`           | Text          |                                                                                |\n| `Extra`             | Text          |                                                                                |\n| `File Path`         | Text          |                                                                                |\n| `Full Citation`     | Text          | Format based on the Zotero setting for **Export → Quick Copy → Item Format**   |\n| `In-Text Citation`  | Text          | Format based on the Zotero setting for **Export → Quick Copy → Item Format**   |\n| `Item Type`         | Select        |                                                                                |\n| `Place`             | Text          |                                                                                |\n| `Proceedings Title` | Text          |                                                                                |\n| `Publication`       | Text          |                                                                                |\n| `Series Title`      | Text          |                                                                                |\n| `Short Title`       | Text          |                                                                                |\n| `Tags`              | Multi-select  |                                                                                |\n| `Title`             | Text          |                                                                                |\n| `URL`               | URL           |                                                                                |\n| `Year`              | Number        |                                                                                |\n| `Zotero URI`        | URL           | Opens items in web library if signed in to Zotero                              |\n\n## Usage Guides\n\nFor more visual guides of setting up and using Notero, see the following\nresources made by wonderful members of the community.\n\n\u003e [!NOTE]\n\u003e Some aspects of these resources may be outdated, so be sure to refer to this\n\u003e README for the latest information.\n\n- [Using Notion and Zotero to build a literature tracker](https://sciquest.netlify.app/posts/notion_literature/)\n  (blog post) by [Jewel Johnson](https://jeweljohnsonj.github.io/jewel_resume/)\n- [How To Sync Zotero → Notion // Research Paper Workflow (2023 Tutorial)](https://youtu.be/8RFFxFcrLCo)\n  (video) by [Holly Jane](https://hollyjane.org/)\n- [Smart notetaking by starting with integrating Zotero and Notion: A first step](https://youtu.be/4Z_5tskdNsY?t=1173)\n  (video) by [Dr. Jingjing Lin](https://jingjing-lin.com/)\n\n_If you'd like to share how you use Notero and want to be listed here, please\nfeel free to submit a PR or [contact me](https://github.com/dvanoni)!_\n\n## Frequently Asked Questions\n\n### How to sync from Notion back into Zotero\n\nBidirectional sync between Notion and Zotero, while desirable, falls outside the\nscope of this plugin. Implementing this functionality would require developing a\nseparate hosted service that could both listen for\n[Notion webhooks](https://developers.notion.com/reference/webhooks) and interact\nwith the Zotero API to propagate changes. While technically feasible as a\nstandalone project, this capability is not part of Notero's functionality.\n\n### How to sync attached files into Notion\n\nThere currently isn't a good way to sync files or link to local files due to the\nfollowing limitations with Notion:\n\n- The Notion API [does not currently support uploading files](https://developers.notion.com/reference/file-object#externally-hosted-files-vs-files-hosted-by-notion).\n- Notion only supports `http:` and `https:` URLs, so it's not possible to link\n  directly to the file using a `file:` URL.\n\nFor now, the best workarounds are:\n\n- Use the `File Path` property to point you to the location of the local file.\n- If you sync your files into your Zotero account, you can open the Zotero web\n  interface from the `Zotero URI` property and then open the file from there.\n\n### How to bulk sync existing items\n\nTo sync multiple items that are already in a monitored collection, you can do so\nfrom the collection or item context menus.\nSee the [Syncing Items](#syncing-items) section above.\n\n### How to fix Notion API errors\n\n#### Could not find database\n\nIf you receive the following error:\n\n\u003e APIResponseError: Could not find database with ID: _xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_\n\nThis most likely means you have not given Notero access to your Notion database.\nEnsure you follow the steps in the\n[Configure Notion Database](#configure-notion-database) section. Clicking the\n**•••** button in the top-right corner of your database should show a connection\nfor the Notero integration.\n\n#### Can't update a page that is archived\n\nIf you receive the following error:\n\n\u003e APIResponseError: Can't update a page that is archived. You must unarchive the\n\u003e page before updating.\n\nThis can happen when Notero tries to sync an item that already had a Notion page\ncreated for it from a previous sync, but that page has since been deleted.\n(Note that deleting a Notion page moves it into the trash, and the Notion API\nrefers to this as \"archived.\")\n\nAs described in the [How Notero Works](#how-notero-works) section, Notero\nassociates Zotero items with Notion pages through a link named `Notion` attached\nto the item. To resolve the issue, delete this link attachment on the offending\nitem(s) and then perform the sync again.\n\n#### Not a property that exists\n\nIf you receive the following error:\n\n\u003e APIResponseError: _property_ is not a property that exists\n\nThis can happen if you previously synced items into one Notion database and then\nchange your Notero preferences to specify a different database. Notero may be\ntrying to update pages in the old database instead of creating pages in the new\ndatabase, and this error can occur if different properties were configured in\nthe different databases.\n\nTo solve this, you should delete the old database in Notion and then permanently\ndelete it from the Trash in Notion.\n\n## Example Notion Databases\n\nWe provide some example Notion databases that have been configured with all the\nproperties synced by Notero.\n\nOnce you've opened one of the examples, click the **Duplicate** button in the\ntop-right corner of the page to duplicate it into your Notion workspace.\n\n### [Basic Example](https://dvanoni.notion.site/25128626a44f80f79295d1dec1ab5910)\n\nAn empty database that contains only the properties synced by Notero.\nUseful if you want to start from scratch and customize it yourself.\n\n### [Advanced Example](https://dvanoni.notion.site/24d28626a44f800ea459dcce841443ff)\n\nA database with multiple views and some sample entries.\nSee below for descriptions of how you can use the different views.\n\n#### Bibliographic Info Table View\n\n- Table view enables easy editing of entries.\n- Easily navigate to the original source by clicking on the `DOI` or `URL` property.\n  - DOIs for books may need to be copy \u0026 pasted manually from the `Extra`\n    field in Zotero.\n- Click on the `Zotero URI` property to view/edit the entry in Zotero or to\n  export the bibliography entry in a different citation style.\n\n#### Reading Status Board View\n\n- Keep track of promising references you need to locate, books and articles you\n  requested via interlibrary loan, and works that are relevant enough to warrant\n  taking in-depth notes or writing a memo.\n\n#### Literature Review Table View\n\n- Quickly analyze and compare attributes of literature you are reviewing\n  (e.g., theoretical framework, sample, methods used, key findings, etc.)\n- Easily link to other works using the `Related References` property\n  (e.g., articles in the same special issue, book chapters in the same edited\n  book, studies and commentary that respond to or extend other works).\n\n#### Books Gallery View\n\n- Add a cover image (e.g., right click → copy image address from Amazon).\n- Keep track of which books you own, borrow, and lend to others.\n  - Add due dates and reminders for library books and interlibrary loans.\n\n## Development\n\nNotero was scaffolded with [generator-zotero-plugin][] and uses build scripts\nheavily inspired by [zotero-plugin][].\nMany thanks to [@retorquere](https://github.com/retorquere) for creating these.\n\n### Local Setup\n\nThe steps below are based on the [Zotero Plugin Development][plugin-development]\ndocumentation and should allow you to build and run Notero yourself.\n\n1.  To avoid any potential damage to your default Zotero profile, you can\n    [create a new profile][zotero-profiles] for development purposes.\n\n2.  Create a file named `zotero.config.json` that will contain the config\n    options used to start Zotero.\n    See [`zotero.config.example.json`](zotero.config.example.json) for an\n    example file that has descriptions of all available config options.\n\n3.  Install dependencies:\n\n        npm ci\n\n4.  Build Notero and start Zotero with the plugin installed:\n\n        npm start\n\n    Alternatively, you can start your desired beta or dev version of Zotero:\n\n        npm run start:beta\n        npm run start:dev\n\n    The `start` script performs a number of steps:\n    1.  Run `scripts/build.mts` to build the plugin into the `build` directory\n        and watch for changes, rebuilding when necessary.\n    2.  Use [web-ext][] to start Zotero with the profile specified in\n        `zotero.config.json` and install the plugin as temporary, reloading when\n        the plugin is rebuilt.\n    3.  Write Zotero debug output to the `logFile` if specified in\n        `zotero.config.json`.\n\n[generator-zotero-plugin]: https://github.com/retorquere/generator-zotero-plugin\n[zotero-plugin]: https://github.com/retorquere/zotero-plugin\n[plugin-development]: https://www.zotero.org/support/dev/client_coding/plugin_development\n[zotero-profiles]: https://www.zotero.org/support/kb/multiple_profiles\n[web-ext]: https://github.com/mozilla/web-ext\n\n### Releasing a New Version\n\nReleases are performed via GitHub Actions. The\n[`release`](.github/workflows/release.yml) workflow defines the following jobs:\n\n#### `release-please`\n\nThis job uses the [release-please][] action to create release PRs when new\nuser-facing commits are pushed to the `main` branch. A release PR will bump the\npackage version and update the changelog. When the PR is merged, this job then\ncreates a new version tag and GitHub release.\n\n#### `publish-artifacts`\n\nThis job runs when a new release is created by the `release-please` job. It\nbuilds the `.xpi` file and publishes it to the release. It also generates an\nupdated manifest file and publishes it to the [`release`][release-tag] release.\n\n[release-please]: https://github.com/googleapis/release-please-action\n[release-tag]: https://github.com/dvanoni/notero/releases/tag/release\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdvanoni%2Fnotero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdvanoni%2Fnotero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdvanoni%2Fnotero/lists"}