Repository files navigation

Notero is aZotero plugin for syncingitems and notes intoNotion. To use it:

1. 💾Install the Notero plugin into Zotero.
2. 📔Connect and configure your Notion database.
3. 📁 Choose your Zotero collections to monitor.
4. 📝 Add or update items in your collections.
5. 🔄 Watch your items sync into Notion!

Concept by@arhoff 👩🏻‍🔬 |Built with 💜 by@dvanoni

• Why Use Notero?
• How Notero Works
• Installation and Setup
• Usage Guides
• Frequently Asked Questions
• Example Notion Databases
• Development

• Integrate your reference manager, task list, reading notes, analytical tables,and drafts in one location.
• Easily link to references when writing in Notion.
• Create custom views to filter and sort large reference lists by project,tag, author, etc.
• Backlinks make it easy to locate any of the notes and drafts that mentiona reference.
• Link references to entries in other databases, such as projects, tasks,manuscripts in your publication pipeline, publishing outlets, etc.

The Notero plugin watches for Zotero items being added to or modified withinany collections that you specify in the Notero preferences. Whenever an itemis added or modified, Notero does a few things:

• Save a page with the Zotero item's properties (title, authors, etc.) into theNotion database specified in Notero preferences.
• Add anotion tag to the Zotero item.
• Add an attachment to the Zotero item that links to the page in Notion.

In addition to providing a convenient way to open a Notion page from Zotero,the link attachment also serves as a reference for Notero so that it can updatethe corresponding Notion page for a given Zotero item.

By default, Notero will sync items in your monitored collections whenever theyare modified. You can disable this functionality by unchecking theSync whenitems are modified option in the Notero preferences.

You can also sync items from the collection or item context menus (right-click):

• To sync all items in a collection, open the context menu for the collectionand selectSync Items to Notion.
• To sync one item or multiple items, select the item(s) in the main pane, openthe context menu, and selectSync to Notion.

Zotero notes associated with an item can be synced into Notion as content of thecorresponding page for that item. As with regular items, you can manually syncnotes using theSync to Notion option in the context menu.

Automatic syncing of notes can be enabled via theSync notes option in theNotero preferences. When enabled, notes will automatically sync whenever theyare modified. Additionally, when a regular item is synced, all of its notes willalso sync if they have not already.

To sync annotations (notes and highlights) from a PDF, you'll first need toextract them into a Zotero note:

1. Select an item or PDF, open the context menu, and selectAdd Note from Annotations.
2. If desired, enable highlight colors from the menu at the top-right of thenote panel.

Using Notero involves installing the plugin in Zotero and connecting it to aNotion database. Detailed setup instructions are below.

1. Download the latest release of the.xpi file.
   • Alternatively, download the.xpi file from theAssets section of thelatest release page.
   • Firefox users: Right-click the download link and chooseSave Link As...to download the file.
2. Open the Zotero Plugins Manager via theTools → Plugins menu item.
3. Install the.xpi file by either:
   • dragging and dropping it into the Plugins Manager windowor
   • selecting it using theInstall Plugin From File... option in thegear menu in the top-right corner of the window
4. Open the Notero preferences from either theTools → Notero Preferences...menu item or the sidebar in the main Zotero preferences window.
5. Configure the Notero preferences as desired.

1. Start the Notion connection process by clicking theConnect to Notionbutton in the Notero preferences. This will open the Notion connection pagein your default web browser.
2. On the Notion connection page, select your desired workspace from the menuat the top (if you have multiple). Then, clickNext.
3. On the next page, choose whether you want to use a template database orconnect to an existing database page.
   • If you choose to use a template, thebasic exampledatabase will be duplicated into your workspace.
   • If you choose to select an existing database, you can search for and selectyour preferred database on the next page. You can also select no databaseand connect one later in Notion.
4. ClickAllow access to give Notero access to your Notion workspace anddatabase. You will then be redirected to a page that prompts you to openZotero.
5. ClickOpen Zotero to complete the connection process in Zotero. TheNotero preferences should show that you are connected to your Notionworkspace.
   • If Zotero does not open or successfully connect to Notion, copy theconnection token from the Notion connection page and paste it into theConnection Token field in Notero preferences.

If you choose not to use the template database during the Notion connectionprocess, you will need to create your own database. Seeexamples below that you can duplicate intoyour workspace, or create one from scratch with properties described in thedatabase properties section below.

To give Notero access to your database, follow these steps:

1. Go to the database page in your workspace.
2. Click on the••• More menu in the top-right corner of the page.
3. Scroll down to and clickConnections.
4. Search for and selectNotero in theSearch for connections... menu.

Notero can sync data for the properties listed below. The only property requiredby Notero is one with theTitle property type. The other properties areoptional, so you can use only the ones that suit your needs.

TheTitle property can be named something other thanName as long as itdoes not conflict with any of the other property names. The name and type ofthe other properties must be configured exactly as specified here. Note thatproperty names are case-sensitive, so the capitalization must match exactly.

Support for customizing properties is planned for the future;see issue#355.

For more visual guides of setting up and using Notero, see the followingresources made by wonderful members of the community.

• Using Notion and Zotero to build a literature tracker(blog post) byJewel Johnson
• How To Sync Zotero → Notion // Research Paper Workflow (2023 Tutorial)(video) byHolly Jane
• Smart notetaking by starting with integrating Zotero and Notion: A first step(video) byDr. Jingjing Lin

If you'd like to share how you use Notero and want to be listed here, pleasefeel free to submit a PR orcontact me!

Bidirectional sync between Notion and Zotero, while desirable, falls outside thescope of this plugin. Implementing this functionality would require developing aseparate hosted service that could both listen forNotion webhooks and interactwith the Zotero API to propagate changes. While technically feasible as astandalone project, this capability is not part of Notero's functionality.

There currently isn't a good way to sync files or link to local files due to thefollowing limitations with Notion:

• The Notion APIdoes not currently support uploading files.
• Notion only supportshttp: andhttps: URLs, so it's not possible to linkdirectly to the file using afile: URL.

For now, the best workarounds are:

• Use theFile Path property to point you to the location of the local file.
• If you sync your files into your Zotero account, you can open the Zotero webinterface from theZotero URI property and then open the file from there.

To sync multiple items that are already in a monitored collection, you can do sofrom the collection or item context menus.See theSyncing Items section above.

If you receive the following error:

APIResponseError: Could not find database with ID:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

This most likely means you have not given Notero access to your Notion database.Ensure you follow the steps in theConfigure Notion Database section. Clicking the••• button in the top-right corner of your database should show a connectionfor the Notero integration.

If you receive the following error:

APIResponseError: Can't update a page that is archived. You must unarchive thepage before updating.

This can happen when Notero tries to sync an item that already had a Notion pagecreated for it from a previous sync, but that page has since been deleted.(Note that deleting a Notion page moves it into the trash, and the Notion APIrefers to this as "archived.")

As described in theHow Notero Works section, Noteroassociates Zotero items with Notion pages through a link namedNotion attachedto the item. To resolve the issue, delete this link attachment on the offendingitem(s) and then perform the sync again.

If you receive the following error:

APIResponseError:property is not a property that exists

This can happen if you previously synced items into one Notion database and thenchange your Notero preferences to specify a different database. Notero may betrying to update pages in the old database instead of creating pages in the newdatabase, and this error can occur if different properties were configured inthe different databases.

To solve this, you should delete the old database in Notion and then permanentlydelete it from the Trash in Notion.

We provide some example Notion databases that have been configured with all theproperties synced by Notero.

Once you've opened one of the examples, click theDuplicate button in thetop-right corner of the page to duplicate it into your Notion workspace.

An empty database that contains only the properties synced by Notero.Useful if you want to start from scratch and customize it yourself.

A database with multiple views and some sample entries.See below for descriptions of how you can use the different views.

• Table view enables easy editing of entries.
• Easily navigate to the original source by clicking on theDOI orURL property.
  • DOIs for books may need to be copy & pasted manually from theExtrafield in Zotero.
• Click on theZotero URI property to view/edit the entry in Zotero or toexport the bibliography entry in a different citation style.

• Keep track of promising references you need to locate, books and articles yourequested via interlibrary loan, and works that are relevant enough to warranttaking in-depth notes or writing a memo.

• Quickly analyze and compare attributes of literature you are reviewing(e.g., theoretical framework, sample, methods used, key findings, etc.)
• Easily link to other works using theRelated References property(e.g., articles in the same special issue, book chapters in the same editedbook, studies and commentary that respond to or extend other works).

• Add a cover image (e.g., right click → copy image address from Amazon).
• Keep track of which books you own, borrow, and lend to others.
  • Add due dates and reminders for library books and interlibrary loans.

Notero was scaffolded withgenerator-zotero-plugin and uses build scriptsheavily inspired byzotero-plugin.Many thanks to@retorquere for creating these.

The steps below are based on theZotero Plugin Developmentdocumentation and should allow you to build and run Notero yourself.

1. To avoid any potential damage to your default Zotero profile, you cancreate a new profile for development purposes.

2. Create a file namedzotero.config.json that will contain the configoptions used to start Zotero.Seezotero.config.example.json for anexample file that has descriptions of all available config options.

3. Install dependencies:

   npm ci

4. Build Notero and start Zotero with the plugin installed:

   npm start

   Alternatively, you can start your desired beta or dev version of Zotero:

   npm run start:betanpm run start:dev

   Thestart script performs a number of steps:

   1. Runscripts/build.mts to build the plugin into thebuild directoryand watch for changes, rebuilding when necessary.
   2. Useweb-ext to start Zotero with the profile specified inzotero.config.json and install the plugin as temporary, reloading whenthe plugin is rebuilt.
   3. Write Zotero debug output to thelogFile if specified inzotero.config.json.

Releases are performed via GitHub Actions. Therelease workflow defines the following jobs:

This job uses therelease-please action to create release PRs when newuser-facing commits are pushed to themain branch. A release PR will bump thepackage version and update the changelog. When the PR is merged, this job thencreates a new version tag and GitHub release.

This job runs when a new release is created by therelease-please job. Itbuilds the.xpi file and publishes it to the release. It also generates anupdated manifest file and publishes it to therelease release.