version 1.9.0

New features

• Group highlights by first-level chapter: each book can become a single note whose highlights are grouped under ## chapter headings, with a clickable table of contents at the top. Enable it in Formatting Options; works best with "Write highlights directly to vault files".

Fixes

• Linux: send the obsidian:// link through calibre's own env-sanitized URL handler (calibre.gui2.open_url) so it launches reliably from calibre's bundled environment. The old raw OS command (xdg-open/open/startfile) is now an optional "Advanced" override in Other Options.
• Settings dialogs: both the Formatting Options and Other Options windows are now freely resizable and their description text wraps instead of forcing the window too wide. Long descriptions live in a scroll area with the OK/Cancel buttons always visible.

1.8.1-beta (Linux obsidian:// opener test build)

Linux test build. This is 1.8.0 plus a fix for the obsidian:// URI not opening on Linux from
inside calibre. It's published for testing — please try it and report back before it goes into a
normal release.

The fix opens the obsidian:// link through calibre's own open_url, which restores the bundled
environment (LD_LIBRARY_PATH etc.) before launching, instead of a raw xdg-open / webbrowser.

Install

Download highlights-to-obsidian-1.8.1.zip below (the asset — not "Source code"), then in
calibre: Preferences → Plugins → Load plugin from file and select the zip. Restart calibre.

How to test

Make sure "open Obsidian with the OS's command" is unchecked, then send a highlight — ideally
Obsidian opens the note directly, with no browser step.

If a browser still opens, run:

xdg-mime query default x-scheme-handler/obsidian

If that returns nothing, your system can't open obsidian:// directly (common with the AppImage
build of Obsidian); in that case enable "Write highlights directly to vault files", which skips the
URI and the browser entirely.

version 1.8.0

Install

Download highlights-to-obsidian-1.8.0.zip below (the asset — not "Source code"), then in
calibre: Preferences → Plugins → Load plugin from file and select the zip. Restart calibre.

What's new since 1.7.0

• Note template files — base each new note on a template file in your vault (e.g.
  Reference/Templates/Book) instead of the header field. Its content becomes the note's
  header/scaffold with H2O's {placeholders} filled in — a natural home for YAML frontmatter.
  Set it in Config → Formatting Options → "Note template file".
• Frontmatter — the :yaml spec plus new guidance make it easy to add YAML frontmatter via the
  header or a template. It lands at the top of the note, isn't duplicated on later sends, and is
  preserved in merge mode.
• "Vault not found" guard — H2O now warns when the "Obsidian vault name" looks like a folder
  path, a common cause of Obsidian's "Vault not found" error.

version 1.7.0

Highlights to Obsidian v1.7.0

A feature release with new formatting options, multi-user support, sturdier error handling, and a bilingual user guide.
本次为功能更新:新增格式化选项、多用户支持、更稳健的错误处理,以及双语使用指南。

⚠️ Behavior change / 行为变更

• Clicking the H2O toolbar button now sends new highlights directly instead of opening the full menu. All actions are still available from the button's dropdown arrow.
  点击 H2O 工具栏按钮现在会直接发送新增高亮,不再弹出整个菜单;全部操作仍在按钮的下拉箭头里。

✨ New features / 新功能

• {if_notes}...{end_if_notes} conditional blocks — include part of the body only for highlights that have notes.
  {if_notes}...{end_if_notes} 条件块 —— 让 body 的某部分仅在高亮有批注时出现。
• {blockid} placeholder — the highlight's uuid sanitized for use as an Obsidian ^block id (fixes block ids broken by _). Put ^{blockid} at the end of a highlight.
  {blockid} 占位符 —— 把 uuid 处理成可用的 Obsidian ^块id(修复 _ 导致的块 id 异常);在高亮末尾放 ^{blockid}。
• {user} / {usertype} placeholders + "Send highlights from ALL users" option (default off: only your own are sent). Useful when several people annotate via the content server.
  {user} / {usertype} 占位符 + 「发送全部用户」选项(默认关闭,只发本人)。适合多人通过内容服务器各自批注的场景。

🔧 Improvements / 改进

• Clearer error dialogs — separate messages for configuration problems, vault-write failures, and Obsidian-URI errors, instead of one generic error.
  更清晰的错误提示 —— 配置问题 / 写入失败 / URI 错误分别给出针对性提示。
• Logging — sends and failures (with full tracebacks) are written to calibre's debug output and a rotating log file (<calibre config>/plugins/highlights_to_obsidian.log).
  日志 —— 发送过程与失败(含完整堆栈)写入 calibre 调试输出和滚动日志文件。
• Clarified the "Obsidian vault name" vs "Vault folder path" settings.
  厘清「Obsidian vault name」与「Vault folder path」两个设置。

📖 Docs / 文档

• New bilingual (EN/中文) user guide: docs/user-guide.md.
  新增中英双语使用指南:docs/user-guide.md。

🛠 Internal / 内部

• Added a build.py packaging script; release zips are no longer committed to the repo.
  新增 build.py 打包脚本;发布用的 zip 不再提交进仓库。

🙏 Acknowledgements / 致谢

• Fork of jm289765/highlights-to-obsidian (MIT).
  本项目 fork 自 jm289765/highlights-to-obsidian(MIT)。
• The {if_notes}, {blockid}, error-handling, and multi-user ideas were inspired by gmcheck's v1.5.1 fork.
  {if_notes}、{blockid}、错误处理与多用户等想法受 gmcheck 的 v1.5.1 fork 启发。

Install / 安装

Download highlights-to-obsidian-1.7.0.zip below, then in calibre: Preferences → Plugins → Load plugin from file, and restart.
下载下方的 highlights-to-obsidian-1.7.0.zip,在 calibre 里:Preferences → Plugins → Load plugin from file,然后重启。

version 1.6.0

Highlights to Obsidian v1.6.0

New features

• New formatting options:
  • {chaptertitle} — the chapter / table-of-contents section the highlight is in (#1)
  • {color} and {colorlabel} — the highlight's color, plus an optional color → label mapping (jm289765#5, jm289765#8)
  • {format} — the book format the highlight is in (e.g. EPUB) (jm289765#5)
  • Book metadata: {calibreid}, {isbn}, {lccn}, {identifiers}, {pubdate}, {tags} (jm289765#5)
• {x:yaml} format spec — makes any value safe inside Obsidian YAML frontmatter, e.g. {title:yaml} for a title containing ":" (jm289765#9)
• "Keep notes sorted and preserve your edits" (write-to-file mode) — inserts each new highlight at its correct sorted position and updates existing ones in place, instead of appending at the bottom, while keeping your manual edits (jm289765#13)
• Read annotations from a custom column — e.g. one populated by the Annotations plugin; sends the column content as the note body, one note per book (jm289765#14)
• "Only send these highlight colors" — an optional color filter (jm289765#8)
• Open Obsidian with the OS's command on all platforms — the former Linux-only option now works on Windows and macOS too (jm289765#7)

Fixes

• The sort key is now forgiving of stray whitespace and capitalization (a trailing space used to silently disable sorting), and the config warns when you enter a sort key that isn't a real formatting option (jm289765#11)

Requires calibre 6.10 or newer.

Install

Download highlights-to-obsidian-1.6.0.zip below and load it via calibre's Preferences → Plugins → Load plugin from file.

version 1.5.0

Highlights to Obsidian v1.5.0

New features

• Write highlights directly to vault files. A new option under Other Options lets H2O write notes straight into your vault folder instead of using the obsidian:// URI. Set your vault's folder path and tick "Write highlights directly to vault files". This avoids highlights being dropped when Obsidian (or the vault) isn't open, removes the note-length limit, and doesn't require Obsidian to be running.
• Duplicate-proof sending. Highlights are now tracked by their unique ID, so sending the same highlight twice no longer creates duplicate notes. A highlight you edit in calibre is re-sent the next time you send new highlights.
• Sending the new highlights of selected books no longer hides new highlights in other books from "Send New Highlights".

Fixes

• Fixed the "body format for highlights without notes" option: when left empty it now correctly falls back to the normal body format instead of producing empty notes.
• Converted the remaining Qt enums to the scoped (PyQt6) form, so the plugin no longer relies on calibre's enum-compatibility shims.

Internal

• "Resend Previously Sent Highlights" now replays the exact last batch that was sent.
• Selected-book sends are filtered in calibre's database for better performance.
• Added a unit-test suite.

Requires calibre 6.10 or newer.

Install

Download highlights-to-obsidian-1.5.0.zip below and load it via calibre's Preferences → Plugins → Load plugin from file.