org-notion

Many moons ago I used Notion.so as a notes and collaboration tool for work. It's easy to use and is (in my opinion) the best web-based solution out there. I have always used Org-mode for personal ventures of course, but it is a pain to integrate with non-tech folks. Even tech folks will roll their eyes if your company-hosted repo has a README.org instead of the tried and true README.md. I decided to abandon Notion.so because I couldn't wait for the overdue official API to be released, and was unsatisfied with the unofficial variants. Nowadays, that story has changed. As of 2021 the official API is available and ready for action.

This package wraps the full Notion API with support for all web requests and object types. The requests are dispatched asynchronously via the methods specializing on the org-notion-request EIEIO class instance. The responses are parsed to create a subclass instance of org-notion-object which contain the actual contents as org-notion-rich-text instances. This is the low-level interface which can be hacked to your liking.

All classes are shown below. There's an abstract org-notion-class which all classes inherit as well as a special org-notion-cache class which stores a cache of org-notion-object instances.

org-notion-class                      
  +--org-notion-request               
  +--org-notion-cache                 
  +--org-notion-object           
  |    +--org-notion-block       
  |    +--org-notion-page        
  |    +--org-notion-database    
  |    +--org-notion-user        
  +--org-notion-rich-text             
  |    +--org-notion-inline-equation  
  |    +--org-notion-inline-mention   
  |    +--org-notion-inline-text      

The parsing is achieved with the help of org-element and json.el. An org-notion-mode minor-mode is provided for interacting with the API from an Org buffer and custom properties are used to keep headlines/files in sync with their Notion counterparts.

org-notion only depends on built-in Emacs libraries. To install, simply clone the repo:

git clone https://github.com/richardwesthaver/org-notion
# OR `hg clone https://hg.rwest.io/org-notion`

and make sure your load-path is setup correctly in your config:

(add-to-list 'load-path "/path/to/org-notion")

Now you can load the package with:

(require 'org-notion)

This package will be uploaded to MELPA upon reaching v1.0.0.

You should create a private integration on the Notion side if you haven't already. This will generate a new Internal Integration Token which is used to authenticate API requests from Emacs.

When running a command for the first time such as org-notion-get-users you will be prompted for your token. This is cached internally for future calls but will not persist across sessions (after restarting the emacs daemon).

The default behavior is to first check with auth-sources before sending requests (~/.authinfo or ~/.authinfo.gpg). This is highly recommended as it avoids the prompt and is more secure. You can disable the check if you wish to temporarily use a different token with (setq org-notion-check-auth-source nil).

The autoloaded functions in this package provide the high-level interface. Most notable of these is org-notion-mode, which is a minor-mode you can add as a hook to org-mode.

(add-hook 'org-mode-hook #'org-notion-mode)

You can customize the keymap org-notion-mode-map to your liking. The defauls are show below.

• Notion
  • API docs
  • examples
• Emacs
  • url
  • parsing json
  • ert
  • eieio
  • org-element
• Prior Art
  • ahungry/org-jira
  • RadekMolenda/org-notion