README file from
GithubBookdrop
English | 한국어
Drop a book into your vault. Search by title, author, or ISBN, pick the right edition, and Bookdrop turns it into a clean, templated book note — cover, authors, publisher, ISBN, and description included.
Bookdrop searches four sources and can combine them:
- Kakao Book Search — fast, complete search for books published in Korea.
- Aladin — Korean bookstore data with page count, table of contents, original title, series, and categories.
- Google Books — broad international coverage.
- Open Library — free international catalog with page counts and subjects; no key needed.
After you pick a book, Bookdrop can look up its ISBN in the other sources and fill in whatever is still missing, so Korean and international books land in one consistent format. Then keep a reading log right in the note — status, dates, rating, pages read and quotes — and see it all on a bookshelf view.
The interface is available in English and Korean. It follows Obsidian's language by default, and you can switch it in settings.
Features
- Create a book note — search, choose a result, and get a new note built from your template in the folder you choose.
- Insert at cursor — drop a book info block into the note you're writing. Select text first to search for it immediately.
- Fill frontmatter — complete the properties (author, publisher, ISBN, cover, link, …) of an existing note. The search is pre-filled from the note's
isbn,title, or file name, and existing values are kept unless you choose to overwrite them. - Fill in missing details — after you choose a book, other sources are checked by ISBN and only empty fields are filled (page count, table of contents, cover, full description…).
- Smart fallback — if a search finds nothing, Korean queries try Korean sources next and other queries try international sources.
- ISBN-aware search — paste an ISBN-10 or ISBN-13, with or without hyphens, for an exact match.
- Choose your folder — pick a default folder from your vault, or have Bookdrop ask every time you create a note.
- Full-size covers — Kakao results use the original cover image instead of the small thumbnail.
- Conditional templates —
{{#toc}}…{{/toc}}keeps a section only when the book has that information. - Keyboard friendly — ↑/↓ to move, Enter to choose. Enter is ignored while composing Korean (IME) text.
- English and Korean — interface and default templates in both languages; follows Obsidian or set it yourself.
- Reading log — status, start and finish dates, star rating, pages read and quotes, stored as note properties so Bases, Dataview and search can use them.
- Bookshelf view — one command creates a Bases file (Obsidian 1.9+) with a cover gallery and views for reading, read this year, finished and to read.
- Works on mobile — all requests use Obsidian's built-in
requestUrl.
Commands
| Command | What it does |
|---|---|
| Search for a book and create a note | Search and create a new book note. Also available from the ribbon. |
| Insert book info at cursor | Insert a rendered block into the current note. |
| Fill current note's properties with book info | Add book properties to the active note. |
| Log this book | One window for status, star rating, one-line review, a quote with its page, and a memo. Opens automatically after you create a note (can be turned off). |
| Change reading status | Pick to read, reading, finished or stopped. |
| Start reading this book / Mark this book as finished | Set the status and today's date in one step. |
| Rate this book | 1–5 stars (half stars by typing, e.g. 3.5). |
| Update reading progress | Record the page you reached; the last page marks the book finished. |
| Add a quote to this book | Add the selected text (or a quote you type) with its page under Quotes. |
| Create bookshelf view | Create a Bases file with a cover gallery of your books. |
Setup
Every source is optional — Google Books and Open Library work with no setup at all.
Kakao Book Search
- Sign in at Kakao Developers and create an application.
- Copy the REST API key from the app's keys page.
- Paste it into Settings → Bookdrop → Kakao REST API key and press Test connection.
Aladin
- Get a free TTB key at Aladin TTB (Aladin account required).
- Paste it into Aladin TTB key and press Test connection.
Results from Aladin show the credit line Aladin asks for ("도서 DB 제공: 알라딘 인터넷서점").
Google Books (optional key)
Google Books works without a key. If you search often and hit rate limits (HTTP 429), enable the Books API in Google Cloud Console, create an API key, and add it in settings. You can also restrict results to a language (e.g. en, ko).
Filling in missing details
Under Fill in missing details, turn the feature on or off and choose which sources it may use. When two sources both have a value, the one listed first wins. Values the search result already has are never replaced, except a short or cut-off description, which is replaced by a longer one.
Templates
Templates use {{variable}} placeholders with optional filters:
| Syntax | Output | Use for |
|---|---|---|
{{title}} |
The Courage to Be Disliked | Note body |
{{title:json}} |
"The Courage to Be Disliked" |
Frontmatter — safe with colons and quotes |
{{authors:json}} |
["Ichiro Kishimi","Fumitake Koga"] |
Frontmatter lists |
{{authors:link}} |
[[Ichiro Kishimi]], [[Fumitake Koga]] |
Wikilinks in the body |
{{authors:linkjson}} |
["[[Ichiro Kishimi]]","[[Fumitake Koga]]"] |
Wikilink lists in frontmatter |
{{toc:list}} |
- Chapter 1- Chapter 2 |
Bullet list (arrays or multi-line text) |
{{#series}}Series: {{series}}{{/series}} |
Series: … (or nothing) | Text that appears only when the value exists |
Variables: title, subtitle, originalTitle, author, authors, translator, translators, publisher, publishDate, publishYear, isbn, isbn10, isbn13, pageCount, series categories, subjects, description, toc, coverUrl, link, price, language, source, sources, status, today
The file name format is a template too — for example {{title}} - {{author}} or {{publishYear}} {{title}}. If a book has no cover, lines with an empty image link are removed automatically.
Default note template (English)
The default template follows the interface language. Leave the template field empty to keep using the default; your own edits are kept when you switch languages.
---
title: {{title:json}}
subtitle: {{subtitle:json}}
original_title: {{originalTitle:json}}
author: {{authors:json}}
translator: {{translators:json}}
publisher: {{publisher:json}}
published: {{publishDate:json}}
isbn: {{isbn:json}}
pages: {{pageCount}}
series: {{series:json}}
categories: {{categories:json}}
cover: {{coverUrl:json}}
link: {{link:json}}
source: {{source}}
created: {{today}}
status: {{status:json}}
started:
finished:
rating:
stars:
one_liner:
progress:
tags:
- book
---

# {{title}}
{{#subtitle}}*{{subtitle}}*
{{/subtitle}}- Author: {{author}}
{{#translator}}- Translator: {{translator}}
{{/translator}}- Publisher: {{publisher}}{{#publishDate}} ({{publishDate}}){{/publishDate}}
{{#pageCount}}- Pages: {{pageCount}}
{{/pageCount}}{{#series}}- Series: {{series}}
{{/series}}
## Description
{{description}}
{{#toc}}
## Contents
{{toc}}
{{/toc}}
## Quotes
## Notes
What each source provides
| Field | Kakao | Aladin | Google Books | Open Library |
|---|---|---|---|---|
| Title, authors, publisher, date, ISBN, cover | ✓ | ✓ | ✓ | ✓ |
| Translators | ✓ | ✓ | — | — |
| Subtitle | — | ✓ | ✓ | ✓ |
| Original title, series | — | ✓ | — | — |
| Page count | — | ✓ | ✓ | ✓ |
| Table of contents | — | ✓ | — | — |
| Categories / subjects | — | categories | categories | subjects |
| Price | ✓ | ✓ | some books | — |
| Description | Short excerpt | Full | Full | — |
Reading log
Log window
Right after you create a book note, a log window opens (turn it off under Settings → Reading log → Log the book right after creating its note, or open it any time with Log this book):
- Status — to read, reading, finished or stopped. The date field becomes Started on or Finished on to match.
- My rating — click a star; the left half of a star gives half a star. Keyboard: ← → in half steps, 1–5, 0 to clear.
- One-line review, a sentence to keep (with its page) and a memo (saved with the date).
- Ctrl/Cmd + Enter saves; Skip closes without changes.
Set Status for new notes in settings to start new notes as reading or finished instead of to read.
Properties
Run the reading commands from the command palette (or give them hotkeys) while a book note is open. They write these note properties:
| Property | Set by | Example |
|---|---|---|
status |
Change reading status, Start reading, Mark as finished, Update reading progress | reading |
started |
Starting a book (only if empty) | 2026-10-26 |
finished |
Finishing a book | 2026-11-20 |
rating |
Rate this book — a number, for sorting and filters | 4.5 |
stars |
Rate this book — the same rating as stars, for reading | ★★★★½ |
one_liner |
Log this book — a one-line review | A book about courage |
progress |
Update reading progress (set to the page count when you finish) | 120 |
- Status words can be changed under Settings → Bookdrop → Reading log. Both the English and Korean defaults are always recognised.
- Quotes go under the Quotes heading (also configurable), each with its page:
> quote/> — p. 23. Select text first to use it as the quote. - Bookshelf view: Create bookshelf view (or the button in settings) asks for a file name — Bookshelf by default, or anything you like — and creates that
.basefile in your book folder. The name is remembered for next time; if the file already exists, it is opened. It includes notes tagged#bookor in the book folder. Bases needs Obsidian 1.9 or later.
Installation
From Community Plugins: Settings → Community plugins → Browse → search for Bookdrop.
Manually: download main.js, manifest.json, and styles.css from the latest release and copy them into <your vault>/.obsidian/plugins/bookdrop/. Then reload Obsidian and enable Bookdrop.
Privacy and network use
Bookdrop sends your search query, or the chosen book's ISBN, only to the sources you use:
dapi.kakao.com— Kakao Book Search, with your REST API keywww.aladin.co.kr— Aladin, with your TTB keywww.googleapis.com— Google Books, with your API key if you provide oneopenlibrary.org— Open Library (no key; requests identify the plugin by name as Open Library asks)
You can turn off any source in Fill in missing details. Cover images are loaded from each source's image servers. API keys are stored locally in the plugin's data.json inside your vault. Bookdrop collects no telemetry and sends nothing anywhere else.
Development
npm install
npm run dev # watch and rebuild main.js
npm run build # type-check and build for release
Support
If Bookdrop saves you time, you can support its development: