Notero

Notero is a Zotero plugin for syncing items into Notion. To use it:

1. 📔 Configure your Notion database.
2. 💾 Install the Notero plugin into Zotero.
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

Table of Contents

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

Why Use Notero?

• Allows you to integrate your reference manager, task list, reading notes, analytical tables, and drafts in one location.
• The name of database entries is the in-text citation, which allows you to 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 mention a reference.
• Link references to entries in other databases, such as projects, tasks, manuscripts in your publication pipeline, publishing outlets, etc.

How Notero Works

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

• Save a page with the Zotero item's properties (title, authors, etc.) into the Notion database specified in Notero preferences.
• Add a notion 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 update existing pages instead of creating duplicate pages for a given Zotero item.

Syncing Items

By default, Notero will sync items in your monitored collections whenever they are modified. You can disable this functionality by unchecking the Sync when items are modified option in 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 collection and select Sync Items to Notion.
• To sync one item or multiple items, select the item(s) in the main pane, open the context menu, and select Sync to Notion.

⚠️ Note: To prevent the "sync on modify" functionality from saving to Notion multiple times, Notero does not notify Zotero when the tag and link attachment are added to an item. This means they may not appear in Zotero immediately, and you may need to navigate to a different item and back to make them appear.

Installation and Setup

The latest release of the plugin is available on GitHub. See the changelog for release notes.

Detailed setup instructions are below.

Configure Notion

1. Create the Notion database that you would like to sync Zotero items into.

   See examples below that you can duplicate into your Notion workspace.

2. Create a Notion internal integration at https://www.notion.com/my-integrations and enable all of the "content capabilities."

   Example of integration capabilities settings

   

3. Take note of the internal integration token from the previous step.

4. Share the database with the integration you created.

   From the Notion developer docs:

   1. Go to the database page in your workspace.
   2. Click the ••• on the top right corner of the page.
   3. At the bottom of the pop-up, click Add connections.
   4. Search for and select your integration in the Search for connections... menu.

   Example of share settings from the Notion documentation

   

5. Take note of the database ID.

   From the Notion developer docs:

   To get the database ID, copy the URL of your Notion database. If you're using an inline database, then make sure you're viewing the database as a full page. If you're using the Notion desktop app, then click Share and select Copy link to find the database URL.

   The database ID is the string of characters in the database URL that is between the slash following your workspace name (if you named it) and the question mark. The ID is 32 characters long, containing numbers and letters.

   

6. Configure the database properties as desired. See the database properties section below for more details.

Notion Database Properties

Notero can sync data for the properties listed below. The only property required by Notero is one with the Title property type. The other properties are optional, so you can use only the ones that suit your needs.

The Title property can be named something other than Name as long as it does not conflict with any of the other property names. The name and type of the other properties must be configured exactly as specified here. Note that property names are case-sensitive, so the capitalization must match exactly.

Property Name	Property Type	Notes
Name	Title	Format configurable via the Notion Page Title option in Notero preferences
Abstract	Text
Authors	Text
Collections	Multi-select
Date	Text
Date Added	Date
DOI	URL
Editors	Text
File Path	Text
Full Citation	Text	Format is based on the Zotero setting for Export → Quick Copy → Item Format
In-Text Citation	Text	Currently APA style, but see issue #5
Item Type	Select
Short Title	Text
Tags	Multi-select
Title	Text
URL	URL
Year	Number
Zotero URI	URL	Links do not work; see issue #172

Support for additional properties is planned for the future. See issues: #49 #52 #65

Install and Configure Notero Plugin

1. Download the latest version of the .xpi file.
   • Note for Firefox users: You'll need to right-click the .xpi file link and choose Save Link As... in order to properly download the file.
2. Open the Zotero Add-ons Manager via the Tools → Add-ons menu item.
3. Install the .xpi file by either:
   • dragging and dropping it into the Add-ons Manager window or
   • selecting it using the Install Add-on From File... option in the gear menu in the top-right corner of the window
4. Restart Zotero to activate the plugin.
5. Open the Notero preferences from the Tools → Notero Preferences... menu item, and enter the required preferences.

Usage Guides

For more visual guides of setting up and using Notero, see the following resources made by wonderful members of the community:

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

If you'd like to share how you use Notero and want to be listed here, please feel free to submit a PR or contact me!

Frequently Asked Questions

How to sync from Notion back into Zotero

While this would be nice, it's unfortunately beyond the scope of this plugin. Getting updates from Notion into Zotero would require setting up a hosted service that subscribes to webhooks from Notion and then uses the Zotero API to update items in Zotero. Notion has yet to release official webhook support, but there are some third-party tools that can be used for this. In theory, this is technically possible, but it would be a separate project.

How to sync attached files into Notion

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

• The Notion API does not currently support uploading files.
• Notion only supports http: and https: URLs, so it's not possible to link directly to the file using a file: URL.

For now, the best workarounds are:

• Use the File 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 web interface from the Zotero URI property and then open the file from there.

How to bulk sync existing items

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

How to fix Notion API errors

Could not find database

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 all the steps from the Configure Notion section. Clicking the ••• button in the top-right corner of your database should show a connection for the integration you've created for Notero.

Example of connection settings

Can't update a page that is archived

If you receive the following error:

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

This can happen when Notero tries to sync an item that already had a Notion page created 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 API refers to this as "archived.")

As described in the How Notero Works section, Notero associates Zotero items with Notion pages through a link named Notion attached to the item. To resolve the issue, delete this link attachment on the offending item(s) and then perform the sync again.

Not a property that exists

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 then change your Notero preferences to specify a different database. Notero may be trying to update pages in the old database instead of creating pages in the new database, and this error can occur if different properties were configured in the different databases.

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

Example Notion Databases

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

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

Basic Example

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

Advanced Example

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

Bibliographic Info Table View

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

Reading Status Board View

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

Literature Review Table View

• 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 the Related References property (e.g., articles in the same special issue, book chapters in the same edited book, studies and commentary that respond to or extend other works).

Books Gallery View

• 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.

Development

Notero was scaffolded with generator-zotero-plugin and is built with a fork of zotero-plugin.

Local Setup

The steps below should allow you to build and run Notero yourself.

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

2. Configure Zotero to run the plugin directly from source. Because the start script already handles most of the steps, you only need to ensure your Zotero profile directory has a directory named extensions.

3. Create a zotero-plugin.ini file as described in the zotero-plugin README. This file is used by the zotero-start command to determine where to install the plugin when running a development build.

   Example

   [profile]
   name = dev
   path = /Users/dvanoni/Library/Application Support/Zotero/Profiles/sekg0jb3.dev
   
   [plugin]
   source = build

4. In order to install the forked zotero-plugin package, you must log in to the GitHub Packages npm registry using a GitHub token with the read:packages scope (generate one here):

   npm login --scope=@dvanoni --registry=https://npm.pkg.github.com
   

5. Install dependencies:

   npm ci
   

6. Perform an initial build of the plugin to create the build directory:

   npm run build
   

7. Start Zotero with the plugin installed:

   npm start
   

   The start script runs zotero-start which performs a number of steps:

   1. Executes npm run build to build the plugin into the build directory.

   2. Writes a file containing the absolute path to the build directory into the extensions directory in the Zotero profile directory.

   3. Starts Zotero with the profile specified in zotero-plugin.ini and the following command line arguments:

      -purgecaches -jsconsole -ZoteroDebugText -debugger -datadir profile
      

Releasing a New Version

1. Run the version script (not to be confused with npm version) to run standard-version. This will create a new commit with a bumped package version and updated changelog, and then it will create a version tag on the commit.

   npm run version
   

2. Push the new version to GitHub:

   git push --follow-tags
   

3. GitHub Actions will run the release workflow upon push of a version tag. This workflow will build the .xpi file and then create a GitHub release with the .xpi file.