k2n-highlights 0.2.0

Telegram bot to sync Kindle highlights to Notion

Kindle Highlights 2 Notion Bot

This Telegram bot lets you upload Kindle highlights (APA-style HTML) and automatically imports them into Notion — with formatting, cover image selection, genre tagging, and more.

Disclaimer

I am not a professional programmer, but a hobbyist who writes code with ChatGPT and Gemini for my own needs. Therefore, this code may be funny, silly, or incorrect - I absolutely understand that. If you have any tips on how to improve it, I will be grateful for the hints, but I don't promise that I will be able to implement them.

---

📚 Table of Contents

• Features
• How to use the bot
• Preparation
  • 1. Create a notion database with the required fields
  • 2. Create a connection and connect it to your database
  • 3. Create telegram bot via @BotFather
  • 4. Set up Imgur and get the necessary tokens to upload pictures
• Quick Start
  • Option 1: Run with Docker
  • Option 2: Run manually (Python)
• Telegram bot demo
• Notion Screenshots
• Support

---

✨ Features

• Parses Kindle APA HTML highlights
• Detects title, author, sections, pages, highlight color
• Automatically creates or updates a Notion book page
• Adds Table of Contents with anchor links
• Emoji-based page icons based on genre
• Optional manual cover image upload
• Syncs highlights with dates and metadata
• UPD: Now covers are loaded to Imgur. See the "Preparation" section for necessary instructions

---

🧰 How to use the bot:

1. Install the official Kindle app on your phone/tablet
2. Download the book from which you want to export highlights
3. Click on Highlights - Share
4. Be sure to select Citation style - APA
5. Send the resulting HTML file to your bot
6. If necessary, edit the Title and Author, add a Cover page

Enjoy!

By default after sending highlights the bot will set the status to "Finished" and the "End of reading" date will be set on the day you uploaded the highlights

---

⭐ Preparation:

1. Create a notion database with the required fields

Property name	Property type
Title	Text
Author	Text
Status	Status
End of reading	Date
Year	Text
Genre	Select

Do not change the name of the properties or if you want to - then edit them in notion_client.py

2. Create a connection and connect it to your database

To allow the bot to access your Notion workspace and database, follow these steps:

1️⃣ Create a New Integration in Notion

Go to https://www.notion.so/profile/integrations

• Click +New integration
• Give your integration a name (e.g. Kindle2Notion Bot)
• Select the workspace you want to connect it to
• Under Capabilities, enable: ✅ Read content ✅ Insert content ✅ Update content
• Click Submit
• Copy the Internal Integration Token — you’ll use this as NOTION_API_KEY in your .env or stack.env

2️⃣ Share Your Notion Database with the Integration

• Navigate to the database you want the integration to access.
• Click on the ••• (More options) button at the top-right corner of the page (not the table!)
• Select Connections from the dropdown menu.
• In the pop-up, search for the name of your integration.
• Select your integration and click Confirm to grant it access to the database.

3️⃣ Find Your Notion Database ID

• Open your Notion database in a browser
• Look at the URL — it should look like:

https://www.notion.so/yourworkspace/Book-Highlights-abcd1234ef56789012345678abcdef12

The long string at the end (32 characters)

abcd1234ef56789012345678abcdef12

is your database ID Use this as NOTION_DATABASE_ID in your .env or stack.env

3. Create telegram bot via @BotFather

Use it's Token as TELEGRAM_BOT_TOKEN in your .env or stack.env.

4. Set up Imgur and get the necessary tokens to upload pictures

To allow the bot to upload book cover images to Imgur (for reliable image hosting), you'll need to set up an Imgur application and configure your environment with the required tokens.

1️⃣ Register an Imgur Application

1. Visit Imgur API registration. Login with Google if necessary.
2. Fill out the form:

• Authorization type: OAuth 2 authorization without a callback URL
• Application name: e.g., Kindle Highlights to Notion
• Email: your valid email
• Description: anything (e.g., Bot that uploads Kindle highlights to Notion with cover support)

3. Submit the form.
4. You’ll receive two important credentials:

• Client ID - you’ll use this as IMGUR_CLIENT_ID in your .env or stack.env
• Client Secret - you’ll use this as IMGUR_CLIENT_SECRET in your .env or stack.env

2️⃣ Authorize Your App

1. Open the following URL in your browser, replacing <CLIENT_ID> with your actual Client ID:

   https://api.imgur.com/oauth2/authorize?client_id=<CLIENT_ID>&response_type=token
   

2. Log in to your Imgur account and authorize the app.
3. You’ll be redirected to a URL that looks like:

   https://imgur.com/#access_token=...&expires_in=...&token_type=...&refresh_token=...&account_username=...&account_id=...
   

4. Copy and save the following values from the URL:

• access_token - you’ll use this as IMGUR_ACCESS_TOKEN in your .env or stack.env
• refresh_token - you’ll use this as IMGUR_REFRESH_TOKEN in your .env or stack.env
• account_username - you’ll use this as ACCOUNT_USERNAME in your .env or stack.env

❓ What the Bot Does with These Tokens

It uploads book cover images directly to your Imgur account. If the access token expires, the bot will automatically refresh it using the refresh token. Uploaded images are hosted in your Imgur profile under https://imgur.com/user/<your_account_username> and used as external image URLs in Notion.

---

📦 Installation and Setup Instructions (for Beginners)

🪟 Windows

1. Create a Project Folder

• Open File Explorer (Win + E)
• Create a folder, e.g., D:\Projects\k2n_project
• Open Command Prompt (Win + R, type cmd)

cd /d D:\Projects\k2n_project

2. Create and Activate a Virtual Environment

python -m venv venv
venv\Scripts\activate

✅ (venv) should appear at the beginning of the command line.

3. Install the Bot

pip install k2n-highlights

4. Create and Configure the .env File

copy nul .env

• Open .env in Notepad.

• Fill it based on .env.example:

  TELEGRAM_BOT_TOKEN=your_telegram_token
  NOTION_API_KEY=your_notion_api_key
  NOTION_DATABASE_ID=your_notion_database_id
  
  IMGUR_ACCESS_TOKEN=
  IMGUR_REFRESH_TOKEN=
  IMGUR_CLIENT_ID=
  IMGUR_CLIENT_SECRET=
  IMGUR_ACCOUNT_USERNAME=
  

5. Run the Bot

k2n-highlights

or python -m k2n_highlights

---

🐧 Linux

1. Create a Project Folder

cd ~/Documents
mkdir k2n_project
cd k2n_project

2. Create and Activate a Virtual Environment

python3 -m venv venv
source venv/bin/activate

✅ (venv) should appear.

3. Install the Bot

pip install k2n-highlights

4. Create and Configure the .env File

touch .env
nano .env

Fill the .env file like this:

TELEGRAM_BOT_TOKEN=your_telegram_token
NOTION_API_KEY=your_notion_api_key
NOTION_DATABASE_ID=your_notion_database_id

IMGUR_ACCESS_TOKEN=
IMGUR_REFRESH_TOKEN=
IMGUR_CLIENT_ID=
IMGUR_CLIENT_SECRET=
IMGUR_ACCOUNT_USERNAME=

Save (Ctrl + O, Enter) and exit (Ctrl + X).

5. Run the Bot

k2n-highlights

or

python3 -m k2n_highlights

---

🍏 macOS

1. Create a Project Folder

cd ~/Documents
mkdir k2n_project
cd k2n_project

2. Create and Activate a Virtual Environment

python3 -m venv venv
source venv/bin/activate

✅ (venv) should appear.

3. Install the Bot

pip install k2n-highlights

4. Create and Configure the .env File

touch .env
nano .env

Fill the .env file:

TELEGRAM_BOT_TOKEN=your_telegram_token
NOTION_API_KEY=your_notion_api_key
NOTION_DATABASE_ID=your_notion_database_id

IMGUR_ACCESS_TOKEN=
IMGUR_REFRESH_TOKEN=
IMGUR_CLIENT_ID=
IMGUR_CLIENT_SECRET=
IMGUR_ACCOUNT_USERNAME=

Save and exit.

5. Run the Bot

k2n-highlights

or

python3 -m k2n_highlights

---

⚡ Important: Reactivating the Environment After Restart

Each time you open a new terminal or command prompt window:

1. Navigate to your project folder.
2. Activate the virtual environment again.

Only then run the bot.

---

🛠 For Developers (Advanced Users)

To run the bot directly from the source code:

1. Clone the repository:

   git clone https://github.com/falone/k2n_highlights.git
   cd k2n_highlights
   

2. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   

   (or python -m venv venv ➔ venv\Scripts\activate on Windows)

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure the .env file:

   cp .env.example .env    # (or copy manually on Windows)
   

5. Run the bot:

   python -m k2n_highlights
   

---

✅ .env must be present.
✅ Pip dependencies must be installed.
✅ Working directory = project root.

---

🔐 Environment Variables (.env)

Variable	Description
TELEGRAM_BOT_TOKEN	Your Telegram bot token
NOTION_API_KEY	Notion integration token
NOTION_DATABASE_ID	Notion database ID
IMGUR_ACCESS_TOKEN	Imgur access token
IMGUR_REFRESH_TOKEN	Imgur refresh token
IMGUR_CLIENT_ID	Imgur client id
IMGUR_CLIENT_SECRET	Imgur client secret
IMGUR_ACCOUNT_USERNAME	Imgur account username

---

Don't forget to create a file named .env (see .env.example) with your credentials

---

📱 Telegram bot demo

🖼 Notion Screenshots

📸 Example Output

---

💖 Support

If you find this project useful, you can support me here: