Paperpile Notion Integration

NOTE: This is not an official Paperpile product.

This is a TypeScript CLI to sync your articles from Paperpile to a Notion database. Optionally, you may sync an authors database as well.

NOTE: This will only be maintained as long as Paperpile doesn't develop their own integration with Notion. They have expressed interest, here.

🚧 Overall, this is project is still a work in progress. This shouldn't be used as production-ready software, so there may be failing edge-cases that haven't been considered/tested. Please feel free to open an issue reporting any bugs/edge-cases you may encounter.

While this project is at v1.x.x, this should not be considered production-ready. It follows semantic versioning, and the migration to TypeScript, obviously, breaks compatability with the Python implementation.

• 🏗 Initial Setup
• 🧑‍💻Usage
  • [Recommended] Automatically (via GitHub Workflows)
  • Manually
• 🛠 Commands

🏗 Initial Setup

Prior to using paperpile-notion, you'll need to setup a few things:

1. Gather a BibTeX export (either manually exported from Paperpile or via their "Workflows & Integrations").
2. A configuration file, similar to what you'll find in docs/paperpile-notion.config.js.
3. Your Article database UUID, which you can copy directly from your browser. (It's that 32-character long hexadecimal string – that looks like notion.so/1234567890abcdef1234567890abcdef.)
4. (Optional) Your Author database URL, copied in a similar manner as above.
5. Your Notion Integration Token. Follow along these steps outlined by Notion. Copy the Integration Token that starts with secret_, you'll need this later.

🧑‍💻Usage

[Recommended] Automatically (via GitHub Workflows)

1. Use the template laid out in Sync your Paperpile to Notion
2. Create a new repository secret named NOTION_INTEGRATION_TOKEN by following this article.
3. Edit the paperpile-notion.config.js file you see in the repository root.

Manually

1. Globally install @jmuchovej/paperpile-notion. (You should globally install so that you can access the CLI as a program.) You do not need sudo access to correctly install this program.

   $ npm install -g @jmuchovej/paperpile-notion

2. Ensure that your Notion Integration Token is added to your environment. I recommend using a tool like direnv or dotenv. (paperpile-notion is purpose-built to run as a GitHub Workflow, so this method will receive little support.)
3. Run the sequence of commands that will perform your desired sync state. (To learn more, check out the commands detailed below.)

🛠 Commands

• paperpile-notion articles:clean BIBTEXPATH
• paperpile-notion articles:sync BIBTEXPATH
• paperpile-notion articles:sync-diff BIBTEXPATH
• paperpile-notion authors:clean BIBTEXPATH
• paperpile-notion authors:sync BIBTEXPATH
• paperpile-notion authors:sync-diff BIBTEXPATH

paperpile-notion articles:clean BIBTEXPATH

Cleans up your Articles Database.

USAGE
  $ paperpile-notion articles:clean [BIBTEXPATH] -t <value> [-c <value>] [-h]

FLAGS
  -c, --config=<value>  Path to your config file, if not in /Users/jmuchovej/.config/paperpile-notion/config.js.
  -h, --help            Show CLI help.
  -t, --token=<value>   (required) Your Notion Integration's Token.

DESCRIPTION
  Cleans up your Articles Database.

  1. Removes dangling articles without authors.

EXAMPLES
  $ paperpile-notion articles:clean /path/to/references.bib

  $ paperpile-notion articles:clean /path/to/references.bib -c /path/to/paperpile-notion.config.js

See code: dist/commands/articles/clean.ts

paperpile-notion articles:sync BIBTEXPATH

Syncs your Articles Database with the local BibTeX file.

USAGE
  $ paperpile-notion articles:sync [BIBTEXPATH] -t <value> [-c <value>] [-h]

FLAGS
  -c, --config=<value>  Path to your config file, if not in /Users/jmuchovej/.config/paperpile-notion/config.js.
  -h, --help            Show CLI help.
  -t, --token=<value>   (required) Your Notion Integration's Token.

DESCRIPTION
  Syncs your Articles Database with the local BibTeX file.

  Strictly creates or updates articles based on the ID assigned by Paperpile.

EXAMPLES
  $ paperpile-notion articles:sync /path/to/references.bib

  $ paperpile-notion articles:sync /path/to/references.bib -c /path/to/paperpile-notion.config.js

See code: dist/commands/articles/sync.ts

paperpile-notion articles:sync-diff BIBTEXPATH

describe the command here

USAGE
  $ paperpile-notion articles:sync-diff [BIBTEXPATH] -t <value> [-c <value>] [-h]

FLAGS
  -c, --config=<value>  Path to your config file, if not in /Users/jmuchovej/.config/paperpile-notion/config.js.
  -h, --help            Show CLI help.
  -t, --token=<value>   (required) Your Notion Integration's Token.

DESCRIPTION
  describe the command here

EXAMPLES
  $ paperpile-notion articles:sync-diff /path/to/references.bib

  $ paperpile-notion articles:sync-diff /path/to/references.bib -c /path/to/paperpile-notion.config.js

See code: dist/commands/articles/sync-diff.ts

paperpile-notion authors:clean BIBTEXPATH

Cleans up your Authors Database.

USAGE
  $ paperpile-notion authors:clean [BIBTEXPATH] -t <value> [-c <value>] [-h]

FLAGS
  -c, --config=<value>  Path to your config file, if not in /Users/jmuchovej/.config/paperpile-notion/config.js.
  -h, --help            Show CLI help.
  -t, --token=<value>   (required) Your Notion Integration's Token.

DESCRIPTION
  Cleans up your Authors Database.

  1. Removes dangling authors with no articles.

  2. Attempts to clean up and merge authors and aliases.

EXAMPLES
  $ paperpile-notion authors:clean /path/to/references.bib

  $ paperpile-notion authors:clean /path/to/references.bib -c /path/to/paperpile-notion.config.js

See code: dist/commands/authors/clean.ts

paperpile-notion authors:sync BIBTEXPATH

Syncs your Authors Database with the local BibTeX file.

USAGE
  $ paperpile-notion authors:sync [BIBTEXPATH] -t <value> [-c <value>] [-h]

FLAGS
  -c, --config=<value>  Path to your config file, if not in /Users/jmuchovej/.config/paperpile-notion/config.js.
  -h, --help            Show CLI help.
  -t, --token=<value>   (required) Your Notion Integration's Token.

DESCRIPTION
  Syncs your Authors Database with the local BibTeX file.

  Authors will be created if not present (or if they don't match a manually entered alias). Otherwise, Authors will have
  their name stripped of whitespace and articles consolidation based on matching Aliases.

EXAMPLES
  $ paperpile-notion authors:sync /path/to/references.bib

  $ paperpile-notion authors:sync /path/to/references.bib -c /path/to/paperpile-notion.config.js

See code: dist/commands/authors/sync.ts

paperpile-notion authors:sync-diff BIBTEXPATH

describe the command here

USAGE
  $ paperpile-notion authors:sync-diff [BIBTEXPATH] -t <value> [-c <value>] [-h]

FLAGS
  -c, --config=<value>  Path to your config file, if not in /Users/jmuchovej/.config/paperpile-notion/config.js.
  -h, --help            Show CLI help.
  -t, --token=<value>   (required) Your Notion Integration's Token.

DESCRIPTION
  describe the command here

EXAMPLES
  $ paperpile-notion authors:sync-diff /path/to/references.bib

  $ paperpile-notion authors:sync-diff /path/to/references.bib -c /path/to/paperpile-notion.config.js

See code: dist/commands/authors/sync-diff.ts