search

makinteract / notero-notes

A Zotero plugin for syncing items and notes into Notion
MIT License
9 stars 0 forks source link

readme

Notero-Notes

This is a form of the popular [Notero]() plugin for Zotero. The difference is that this fork allows us to support Notes directly in the Notion database with the field ZoteroNotes (see picture below).

You can create a database in Notion using this template which includes the ZoteroNotes field. Everything else in this plugin is the same as in the original one. Read the documentation below for help.

For a video tutorial please refer to this YouTube video:

Latest release Total downloads Works with Zotero Buy me a coffee

Notero is a Zotero plugin for syncing items and notes 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!

Notero in action

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

Table of Contents

Why Use Notero?

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:

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 the corresponding Notion page 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 the Notero preferences.

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

[!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.

Syncing Notes and PDF Annotations

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

Automatic syncing of notes can be enabled via the Sync notes option in the Notero preferences. When enabled, notes will automatically sync whenever they are modified. Additionally, when a regular item is synced, all of its notes will also sync if they have not already.

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

  1. Select an item or PDF, open the context menu, and select Add Note from Annotations.
  2. If desired, enable highlight colors from the menu at the top-right of the note panel.
Example of creating a note from PDF annotations

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 Notion integration capabilities settings

  3. Take note of the "internal integration secret" from the previous step.

  4. Give your integration access to your database.

    From the Notion developer docs:

    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 click + Add Connections.
    4. Search for and select your integration in the Search for connections... menu.
    Example of connection settings from the Notion documentation Share database with integration

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

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

Property Name Property Type Notes
Name Title Format configurable via the Notion Page Title option in Notero preferences
Abstract Text
Authors Text
Citation Key Text Requires Better BibTeX
Collections Multi-select
Date Text
Date Added Date
Date Modified Date
DOI URL
Editors Text
Extra Text
File Path Text
Full Citation Text Format based on the Zotero setting for Export → Quick Copy → Item Format
In-Text Citation Text Format based on the Zotero setting for Export → Quick Copy → Item Format
Item Type Select
Place Text
Proceedings Title Text
Publication Text
Series Title Text
Short Title Text
Tags Multi-select
Title Text
URL URL
Year Number
Zotero URI URL Opens items in web library if signed in to Zotero
ZoteroNotes Text The text of the notes

Install and Configure Notero Plugin

[!IMPORTANT] Notero requires Zotero version 6.0.27 or above and is also compatible with Zotero 7.

  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. Open the Notero preferences from the Tools → Notero Preferences... menu item, and enter the required preferences.
    • Note for Zotero 7 users: The Notero preferences have moved into a section in the main Zotero preferences window.

Usage Guides

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

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:

For now, the best workarounds are:

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 Share with Notero

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

Reading Status Board View

Literature Review Table View

Books Gallery View

Development

Notero was scaffolded with generator-zotero-plugin and uses build scripts heavily inspired by zotero-plugin. Many thanks to @retorquere for creating these.

Local Setup

The steps below are based on the Zotero Plugin Development documentation and 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. Create a file named zotero.config.json that will contain the config options used to start Zotero. See zotero.config.example.json for an example 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 version of Zotero:

    npm run start-beta

    The start script performs a number of steps:

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

    2. If defined, run the scripts.prestart command specified in zotero.config.json.

    3. Write a file containing the absolute path to the build directory into the extensions directory in the Zotero profile directory.

    4. Remove the extensions.lastAppBuildId and extensions.lastAppVersion lines from prefs.js in the Zotero profile directory.

    5. Start Zotero with the profile specified in zotero.config.json and the following command line arguments:

      -purgecaches -ZoteroDebugText -jsconsole -debugger -datadir profile

    6. If defined, run the scripts.poststart command specified in zotero.config.json.

Releasing a New Version

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

release-please

This job uses the release-please action to create release PRs when new user-facing commits are pushed to the main branch. A release PR will bump the package version and update the changelog. When the PR is merged, this job then creates a new version tag and GitHub release.

publish-artifacts

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