org-notion
Overview
Org-mode is the GNU Emacs major-mode for keeping notes, maintaining TODO lists, and project planning. It is a very powerful text-based system for organizing your life in plaintext.
Notion is a web-based application with a similar purpose. It works well on all platforms and has some cool features including databases, realtime collaboration, and as of 2021 an official API.
org-notion is an Emacs package that uses this API to integrate the
beauty of Notion with your Org-mode workflow.
Status
- state
- ON HOLD
This package is not yet complete. I plan to continue development in the next few months but am open to contribs and chatting about design/features in the meantime. Check the Dev Log for updates.
Introduction
Design
This package wraps the full Notion API with support for all web
requests and object types. The requests are dispatched 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.
Installation
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.
Configuration
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).
Usage
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.
| key | function | description |
|---|---|---|
| C-c n p | org-notion-push | Push local changes to Notion |
| C-c n f | org-notion-pull | Pull remote changes from Notion |
| C-c n o | org-notion-browse | Open Notion page in browser |
| C-c n r s | org-notion-search | Search Notion |
| C-c n r u | org-notion-get-user | Get Notion Users |
Resources
- Notion
- Emacs
- Prior Art
Dev Log
[2023-07-12 Wed] project state
I haven’t done much with this project (sorry!) in the past several months. It’s been a busy start to the year with a series of developments that have taken priority.