Synotion

A Ruby gem to sync Markdown files to Notion pages.

Features

Multiple update modes: create, append, replace, or upsert pages
Flexible page identification by custom properties, filenames, or titles
Automatic Markdown to Notion blocks conversion
Command-line interface
YAML front matter support

Installation

gem install synotion

Or add to your Gemfile:

gem 'synotion'

Quick Start

Create a Notion integration at https://www.notion.so/my-integrations
Share your database with the integration
Run:

synotion sync README.md \
  --api-key=secret_xxx \
  --database-id=your-database-id

Usage

CLI

# Basic usage
synotion sync README.md \
  --api-key=$NOTION_API_KEY \
  --database-id=your-database-id

# Specify update mode
synotion sync CHANGELOG.md \
  --api-key=$NOTION_API_KEY \
  --database-id=your-database-id \
  --mode=append

# Use config file
synotion sync README.md --config=.notion-sync.yml

Ruby API

require 'synotion'

# Configure globally
Synotion.configure do |config|
  config.notion_api_key = ENV['NOTION_API_KEY']
  config.database_id = 'your-database-id'
end

# Sync a file
syncer = Synotion::Syncer.new
result = syncer.sync('README.md')
# => { action: 'created', page_id: 'xxx', mode: :upsert }

# Sync with options
result = syncer.sync('docs/api.md',
  mode: :replace,
  title: 'API Documentation'
)

Configuration File

Create .notion-sync.yml:

notion_api_key: secret_xxx
database_id: your-database-id
update_mode: upsert
unique_property: source_file

Configuration Options

Option	Description	Default
`notion_api_key`	Notion API key (required)	-
`database_id`	Target database ID	-
`page_id`	Target page ID (alternative to database_id)	-
`update_mode`	How to handle existing pages	`:upsert`
`unique_property`	Property for page identification	`'source_file'`
`title_from`	How to extract page title	`:first_heading`
`sync_metadata`	Add last_synced timestamp	`true`

Update Modes

Mode	Behavior
`:create`	Create new page only (skip if exists)
`:append`	Append content to existing page
`:replace`	Replace entire page content
`:upsert`	Update if exists, create if not (default)

Supported Markdown Elements

Headings (H1, H2, H3+)
Paragraphs
Code blocks with syntax highlighting
Bulleted lists
Numbered lists
Quotes
Dividers
Todo items / Checkboxes
Tables (converted to Notion table blocks)
Links (external URLs converted to clickable links)
YAML front matter

Notion Setup

Create an Integration

Go to https://www.notion.so/my-integrations
Click "New integration"
Copy the "Internal Integration Token"

Create a Database

Create a Notion database with these properties:

Property	Type	Purpose
Name	Title	Page title (required)
source_file	Text	File path for unique identification
last_synced	Date	Last sync timestamp (optional)

Share Database

Open your database in Notion
Click "..." → "Add connections"
Select your integration

Development

# Install dependencies
bundle install

# Run tests
bundle exec rspec

# Try in console
bundle exec exe/synotion --help

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/synotion.

License

The gem is available as open source under the terms of the MIT License.

synotion

Runtime