# 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][forum.paperpile/notion]. [forum.paperpile/notion]: https://forum.paperpile.com/t/suggestion-for-notion-hook/ 🚧 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.** [![Version](https://img.shields.io/npm/v/@jmuchovej/paperpile-notion.svg)](https://npmjs.org/package/@jmuchovej/paperpile-notion) [![Downloads/week](https://img.shields.io/npm/dw/@jmuchovej/paperpile-notion.svg)](https://npmjs.org/package/@jmuchovej/paperpile-notion) [![License](https://img.shields.io/npm/l/@jmuchovej/paperpile-notion.svg)](https://github.com/jmuchovej/paperpile-notion/blob/main/package.json) 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**](#-initial-setup) * [**🧑‍💻Usage**](#-usage) * [[Recommended] Automatically (via GitHub Workflows)](#recommended-automatically-via-github-workflows) * [Manually](#manually) * [**🛠 Commands**](#-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`][config]. 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.][notion/new-integration] **Copy the Integration Token that starts with `secret_`**, you'll need this later. [notion/new-integration]: https://developers.notion.com/docs/getting-started#getting-started [config]: docs/config.js # 🧑‍💻Usage ## [Recommended] Automatically (via GitHub Workflows) 1. Use the template laid out in [Sync your Paperpile to Notion][sync-repo] 2. Create a new repository secret named `NOTION_INTEGRATION_TOKEN` by following [this article][secrets]. 3. Edit the `paperpile-notion.config.js` file you see in the repository root. [sync-repo]: https://github.com/jmuchovej/paperpile-notion-starter [secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository ## 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.** ```shell $ 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](#commands) detailed below.) # 🛠 Commands * [`paperpile-notion articles:clean BIBTEXPATH [BIBTEXDIFF]`](#paperpile-notion-articlesclean-bibtexpath-bibtexdiff) * [`paperpile-notion articles:sync BIBTEXPATH [BIBTEXDIFF]`](#paperpile-notion-articlessync-bibtexpath-bibtexdiff) * [`paperpile-notion authors:clean BIBTEXPATH [BIBTEXDIFF]`](#paperpile-notion-authorsclean-bibtexpath-bibtexdiff) * [`paperpile-notion authors:sync BIBTEXPATH [BIBTEXDIFF]`](#paperpile-notion-authorssync-bibtexpath-bibtexdiff) ## `paperpile-notion articles:clean BIBTEXPATH [BIBTEXDIFF]` Cleans up your Articles Database. ``` USAGE $ paperpile-notion articles:clean [BIBTEXPATH] [BIBTEXDIFF] -t [-c ] [-h] ARGUMENTS BIBTEXPATH Path to the BibTeX file you would like to sync with Notion. BIBTEXDIFF Path to the BibTeX file you would like to diff "bibtexPath" against. FLAGS -c, --config= Path to your config file, if not in /Users/jmuchovej/.config/paperpile-notion/config.js. -h, --help Show CLI help. -t, --token= (required) Your Notion Integration Token. (NOTE: If you specify an environment variable of 'NOTION_INTEGRATION_TOKEN', that may be used.) 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 $ paperpile-notion articles:clean /path/to/references.bib -t $ paperpile-notion articles:clean /path/to/references.bib -t -c /path/to/paperpile-notion.config.js $ paperpile-notion articles:clean /path/to/references.bib /path/to/your/previous/references.bib $ paperpile-notion articles:clean /path/to/references.bib /path/to/your/previous/references.bib -t $ paperpile-notion articles:clean /path/to/references.bib /path/to/your/previous/references.bib -t -c /path/to/paperpile-notion.config.js ``` _See code: [dist/commands/articles/clean.ts](https://github.com/jmuchovej/paperpile-notion/blob/v1.3.0/dist/commands/articles/clean.ts)_ ## `paperpile-notion articles:sync BIBTEXPATH [BIBTEXDIFF]` Syncs your Articles Database with the local BibTeX file. ``` USAGE $ paperpile-notion articles:sync [BIBTEXPATH] [BIBTEXDIFF] -t [-c ] [-h] ARGUMENTS BIBTEXPATH Path to the BibTeX file you would like to sync with Notion. BIBTEXDIFF Path to the BibTeX file you would like to diff "bibtexPath" against. FLAGS -c, --config= Path to your config file, if not in /Users/jmuchovej/.config/paperpile-notion/config.js. -h, --help Show CLI help. -t, --token= (required) Your Notion Integration Token. (NOTE: If you specify an environment variable of 'NOTION_INTEGRATION_TOKEN', that may be used.) 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 $ paperpile-notion articles:sync /path/to/references.bib -t $ paperpile-notion articles:sync /path/to/references.bib -t -c /path/to/paperpile-notion.config.js $ paperpile-notion articles:sync /path/to/references.bib /path/to/your/previous/references.bib $ paperpile-notion articles:sync /path/to/references.bib /path/to/your/previous/references.bib -t $ paperpile-notion articles:sync /path/to/references.bib /path/to/your/previous/references.bib -t -c /path/to/paperpile-notion.config.js ``` _See code: [dist/commands/articles/sync.ts](https://github.com/jmuchovej/paperpile-notion/blob/v1.3.0/dist/commands/articles/sync.ts)_ ## `paperpile-notion authors:clean BIBTEXPATH [BIBTEXDIFF]` Cleans up your Authors Database. ``` USAGE $ paperpile-notion authors:clean [BIBTEXPATH] [BIBTEXDIFF] -t [-c ] [-h] ARGUMENTS BIBTEXPATH Path to the BibTeX file you would like to sync with Notion. BIBTEXDIFF Path to the BibTeX file you would like to diff "bibtexPath" against. FLAGS -c, --config= Path to your config file, if not in /Users/jmuchovej/.config/paperpile-notion/config.js. -h, --help Show CLI help. -t, --token= (required) Your Notion Integration Token. (NOTE: If you specify an environment variable of 'NOTION_INTEGRATION_TOKEN', that may be used.) 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 $ paperpile-notion authors:clean /path/to/references.bib -t $ paperpile-notion authors:clean /path/to/references.bib -t -c /path/to/paperpile-notion.config.js $ paperpile-notion authors:clean /path/to/references.bib /path/to/your/previous/references.bib $ paperpile-notion authors:clean /path/to/references.bib /path/to/your/previous/references.bib -t $ paperpile-notion authors:clean /path/to/references.bib /path/to/your/previous/references.bib -t -c /path/to/paperpile-notion.config.js ``` _See code: [dist/commands/authors/clean.ts](https://github.com/jmuchovej/paperpile-notion/blob/v1.3.0/dist/commands/authors/clean.ts)_ ## `paperpile-notion authors:sync BIBTEXPATH [BIBTEXDIFF]` Syncs your Authors Database with the local BibTeX file. ``` USAGE $ paperpile-notion authors:sync [BIBTEXPATH] [BIBTEXDIFF] -t [-c ] [-h] ARGUMENTS BIBTEXPATH Path to the BibTeX file you would like to sync with Notion. BIBTEXDIFF Path to the BibTeX file you would like to diff "bibtexPath" against. FLAGS -c, --config= Path to your config file, if not in /Users/jmuchovej/.config/paperpile-notion/config.js. -h, --help Show CLI help. -t, --token= (required) Your Notion Integration Token. (NOTE: If you specify an environment variable of 'NOTION_INTEGRATION_TOKEN', that may be used.) 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 $ paperpile-notion authors:sync /path/to/references.bib -t $ paperpile-notion authors:sync /path/to/references.bib -t -c /path/to/paperpile-notion.config.js $ paperpile-notion authors:sync /path/to/references.bib /path/to/your/previous/references.bib $ paperpile-notion authors:sync /path/to/references.bib /path/to/your/previous/references.bib -t $ paperpile-notion authors:sync /path/to/references.bib /path/to/your/previous/references.bib -t -c /path/to/paperpile-notion.config.js ``` _See code: [dist/commands/authors/sync.ts](https://github.com/jmuchovej/paperpile-notion/blob/v1.3.0/dist/commands/authors/sync.ts)_