KOHi

Import highlights and notes from KOReader into your Obsidian vault.

KOHi scans your KOReader device for .sdr metadata directories, parses the Lua-serialized annotations, and generates one Markdown note per book — with full control over the output format via Nunjucks templates.

Features

• Auto-detect all 3 KOReader storage modes — book folder, koreader/docsettings, and koreader/hashdocsettings
• Customizable templates — Nunjucks-based templates with access to book metadata, highlights, and chapter grouping
• Selective import — import all books at once, or pick specific ones via fuzzy search
• Clean filenames — illegal characters are sanitized automatically
• Overwrite on re-import — simple, predictable behavior

Usage

1. Connect your Kobo (or other KOReader device) via USB
2. Open Obsidian → Settings → KOHi → set Mount path (e.g. /Volumes/KOBOeReader)
3. Command Palette → KOHi: Import all highlights or KOHi: Import selected highlights
4. Notes appear in your configured output folder

Settings

Template

Notes are generated using Nunjucks templates. You can customize the output format in plugin settings.

Available variables

Book level:

Highlight level (within loops):

Two data structures are provided for flexibility:

• highlights — flat array, original reading order
• chapters — grouped by chapter, each with a name and highlights array

Default template

---
title: "{{title}}"
author: "{{author}}"
{% if language %}language: {{language}}{% endif %}
{% if series %}series: "{{series}}"{% endif %}
{% if seriesIndex != null %}series_index: {{seriesIndex}}{% endif %}
{% if pages != null %}pages: {{pages}}{% endif %}
imported: {{imported}}
---
{% if description %}
{{description}}

---
{% endif %}
{% for chapter in chapters %}
{% if chapter.name %}
## {{chapter.name}}
{% endif %}
{% for h in chapter.highlights %}
> {{h.text}}
{% if h.page %}
>
> — p.{{h.page}}
{% endif %}
{% if h.note %}

> [!note]
> {{h.note}}
{% endif %}

{% endfor %}
{% endfor %}

Flat list (no chapter grouping)

---
title: "{{title}}"
author: "{{author}}"
{% if series %}series: "{{series}}"{% endif %}
{% if seriesIndex != null %}series_index: {{seriesIndex}}{% endif %}
imported: {{imported}}
---
{% if description %}
{{description}}

---
{% endif %}
{% for h in highlights %}
> {{h.text}}
{% if h.page %}
>
> — p.{{h.page}}
{% endif %}
{% if h.note %}

> [!note]
> {{h.note}}
{% endif %}

{% endfor %}

Installation

From community plugins

1. Open Obsidian → Settings → Community plugins → Browse
2. Search for KOHi
3. Click Install, then Enable

Via BRAT

1. Install the BRAT plugin
2. BRAT settings → Add Beta Plugin → paste chiahsien/obsidian-kohi

Manual install

1. Download main.js, manifest.json, and styles.css from the latest release
2. Create a folder <vault>/.obsidian/plugins/kohi/
3. Copy the downloaded files into that folder
4. Restart Obsidian → Settings → Community plugins → Enable KOHi

Build from source

git clone https://github.com/chiahsien/obsidian-kohi.git
cd obsidian-kohi
npm install
npm run build

Then copy main.js, manifest.json, and styles.css into your vault's plugin folder as described above.

Development

Prerequisites

• Obsidian ≥ 1.7.2
• Node.js ≥ 18
• npm

Setup

git clone https://github.com/chiahsien/obsidian-kohi.git
cd obsidian-kohi
npm install

Commands

Project structure

src/
├── types.ts              # Shared interfaces (Book, Highlight, BookData, etc.)
├── lua-parser.ts         # Recursive descent parser for KOReader Lua metadata
├── scanner.ts            # Three-phase .sdr directory scanner
├── book-parser.ts        # Metadata → BookData extraction + chapter grouping
├── note-generator.ts     # Nunjucks template rendering
├── note-writer.ts        # Vault file creation with filename sanitization
├── multi-select-modal.ts # Fuzzy-search book picker modal
├── settings.ts           # Plugin settings tab
└── main.ts               # Plugin entry point + commands

Hot-reload during development

1. Build with npm run dev (watch mode)
2. Symlink or copy the repo into your test vault:

   ln -s /path/to/obsidian-kohi /path/to/vault/.obsidian/plugins/kohi
   

3. Enable the plugin in Obsidian → changes are picked up on reload (Cmd+R)

License

MIT