EPUB Reading Importer

EPUB Transfer to Markdown

Transfer EPUB books into chapter-based Markdown notes.

This plugin is designed for people who keep books and reading notes in a local vault. It converts an EPUB into a folder of Markdown files, keeps image assets together, and creates an index note plus an AI reading guide.

What It Creates

After importing an EPUB, the plugin creates a folder like this:

Books/
  Book Title/
    00 - Index.md
    01 - Introduction.md
    02 - Chapter 1.md
    AI Reading Guide.md
    source.epub
    media/
      image-1.jpg
      image-2.png

00 - Index.md links to all generated chapter notes. media/ contains images copied from the EPUB, so chapter images stay readable after import. If "Keep source EPUB" is enabled, the original EPUB is copied into the book folder as source.epub.

Requirements

This is a desktop-only plugin for macOS and Windows.

You must install pandoc before using the plugin:

• macOS: install pandoc with Homebrew or from the official pandoc installer.
• Windows: install pandoc for Windows and make sure pandoc.exe is available.

The plugin tries to find pandoc automatically.

On macOS it checks:

/opt/homebrew/bin/pandoc
/usr/local/bin/pandoc
/usr/bin/pandoc

On Windows it checks:

C:\Program Files\Pandoc\pandoc.exe
C:\Program Files (x86)\Pandoc\pandoc.exe
%USERPROFILE%\AppData\Local\Pandoc\pandoc.exe
pandoc.exe
pandoc

If pandoc is installed somewhere else, open the plugin settings and enter the full pandoc path manually.

How to Use

1. Install and enable the plugin.
2. Open the command palette.
3. Run Transfer EPUB to Markdown.
4. Select an .epub file.
5. Wait for the import to finish.
6. Open the generated 00 - Index.md file.

You can also click the book icon in the left ribbon.

Settings

• Output folder: the vault folder where imported books are created. The default is Books.
• Pandoc path: optional full path to pandoc. Leave it blank for auto-detection.
• Keep source EPUB: copy the original EPUB into the generated book folder.
• Open index after import: open 00 - Index.md after the import finishes.

Troubleshooting

"pandoc" is not found

Install pandoc first, then restart the app and try again.

If it still fails, set the full pandoc path in the plugin settings.

Examples:

/opt/homebrew/bin/pandoc
C:\Program Files\Pandoc\pandoc.exe

The import works on macOS but fails on Windows

Check that pandoc is installed for Windows. The plugin uses PowerShell Expand-Archive to unzip EPUB files on Windows, so PowerShell must be available.

No readable chapters were found

The EPUB may have an unusual internal structure, DRM protection, or content stored as images instead of HTML text. Try opening the EPUB in a regular EPUB reader first. If the book is mostly scanned pages, the plugin cannot turn those pages into clean text notes.

Images are missing

Make sure the generated media/ folder stays next to the Markdown files. Do not move the chapter notes without moving the media/ folder too.

The generated Markdown looks messy

EPUB files vary a lot. Some books contain clean chapter HTML, while others contain layout-heavy HTML, scanned pages, or unusual navigation files. This plugin tries to create readable Markdown, but the final quality depends on the source EPUB.

Privacy and Permissions

The plugin works locally. It does not send book files or notes to a network service.

It does use local filesystem access to read the selected EPUB and write Markdown files into your vault. It also runs local command-line tools such as pandoc, and on Windows it may run PowerShell for EPUB extraction.

Development

npm install
npm run build

For local testing, copy or symlink this folder into:

<vault>/.obsidian/plugins/epub-reading-importer

Then enable EPUB Transfer to Markdown in community plugins.