Skip to content

Grimmory File Structure & Bookdrop

How to organize book files and use Grimmory's Bookdrop feature for automatic importing and metadata enrichment.

Overview

Grimmory has two ways to ingest books:

  1. Library watch folders — files placed here appear in the library directly, no staging step
  2. Bookdrop — a staging area that auto-detects new files, fetches metadata from online sources, and lets you review before importing

Supported Formats

Category Formats
eBooks EPUB, MOBI, AZW, AZW3, FB2
Documents PDF
Comics CBZ, CBR, CB7
Audiobooks M4B, M4A, MP3, OPUS

When creating a library, you can restrict which formats it will scan via the "Allowed Formats" setting and set a Format Priority order for books that exist in multiple formats.

Library Folders (Watch Mode)

Place books directly in the library folder. Grimmory watches for changes automatically:

/books/
  any_book.epub
  another_book.pdf
  comic.cbz
  audiobook.m4b
  • No specific folder structure required — files can be flat or organized however you like
  • New, changed, or deleted files are detected automatically
  • Metadata is read from embedded file metadata (EPUB/PDF tags) or sidecar files, depending on your library's metadata source setting

Bookdrop (Staging Workflow)

The Bookdrop folder is a separate mount that acts as a staging area:

/bookdrop/
  new_book.epub
  bulk_import/
    book1.pdf
    book2.epub

How it works

  1. Drop files into /bookdrop (on disk, via SMB, or through the web upload UI)
  2. Grimmory auto-detects them and fetches metadata from Google Books, Open Library, and Amazon
  3. Files are staged for review in the web UI — you can edit metadata, correct matches, and assign a destination library
  4. Finalize the import to move the file into the chosen library

Advanced Bookdrop Features

  • Filename pattern extraction — Grimmory can parse author and title from filenames using configurable patterns (e.g., Author - Title.epub)
  • Bulk editing — review and import multiple staged books at once

Docker Volume Mapping

volumes:
  - ./data:/app/data        # application data, settings, metadata cache
  - ./books:/books           # library folder (watched)
  - ./bookdrop:/bookdrop     # staging folder (auto-import + metadata fetch)
  1. For curated additions: Use the Bookdrop — drop files in, let Grimmory fetch metadata, review and approve
  2. For bulk imports with good filenames/metadata: Place directly in the library folder with watch mode enabled
  3. For mixed-format libraries: Set format priority so EPUB is preferred over PDF when both exist

References