Supplement Files

Supplement files are additional files associated with a book, such as companion guides, liner notes, maps, artwork, and errata. Shisho discovers them during library scans.

Main Files and Supplements

Shisho's native main-file formats are EPUB, AZW3, MOBI, CBZ, M4B, and PDF. CBR is not native unless a plugin adds support. Files that are not recognized as main files can be linked to a nearby book as supplements.

A supplement is labeled with its current filename, including the extension, so the label follows the file when the book is renamed or reorganized. A name you set yourself in the file's edit dialog replaces the filename. Shisho does not extract embedded book or file metadata from supplements.

Directory-Based Discovery

For a book stored in its own directory, Shisho recursively links eligible non-main files anywhere below that book directory:

[Author] Book Title/
├── book.epub
├── companion-guide.txt
├── notes.txt
└── extras/
    ├── map.jpg
    └── appendix.txt

All four files other than book.epub are candidates for supplement discovery.

warning

Directory grouping is intentionally broad. If one directory contains unrelated books or general-purpose files, those files may all be attached to the same book. Keep each directory limited to one logical book and its extras.

Root-Level Discovery

For a main file stored directly at a configured library root, Shisho checks files in that same root. A candidate matches when its basename is equal to, or starts with, the main file's basename.

library/
├── My Book.m4b
├── My Book.pdf
├── My Book - Notes.txt
├── My Booklet.jpg
└── Other Book.txt

My Book - Notes.txt and My Booklet.jpg match the My Book.m4b prefix and become supplements. Other Book.txt does not match. My Book.pdf remains a native main file rather than becoming a supplement because main-file extensions are excluded before prefix matching.

Prefix matching is literal and can be broader than expected. For example, My Booklet.jpg matches My Book. Use distinctive main filenames or put the book in its own directory if similarly named files should remain separate.

Exclusions

Discovery skips:

• Native main-file extensions and files already tracked by Shisho as main files.
• Shisho cover files and Sidecar Metadata Files.
• Files matching supplement_exclude_patterns.
• Directories when evaluating root-level candidates.

The default exclusion patterns cover hidden files and common operating-system files. Configure exceptions and additional globs in Configuration instead of relying on repeated manual demotion. Exclusion only skips a file during discovery; it never deletes it. See Empty Directory Cleanup for the files Shisho does remove with an empty directory.

PDF Auto-Demotion

A newly created PDF is automatically imported as a supplement only when all of these conditions are true:

1. It is part of a directory-based book, not a file at a configured library root.
2. Its basename is an exact, case-insensitive match for a configured pdf_supplement_filenames value.
3. The same book directory already has a Shisho book or contains a non-PDF main file, such as EPUB, AZW3, MOBI, CBZ, M4B, or a plugin-registered format.

For example, Supplement.pdf can be auto-demoted beside Book.epub when supplement is configured. My Supplement.pdf is not an exact match for supplement.

The rule runs only when the PDF is first created in Shisho. Existing PDFs are not reclassified by later scans. A root-level PDF remains a main PDF even when its basename matches the configured list.

Removed Supplement Files

When a supplement's file is deleted from disk, Shisho removes it from the book. The library monitor does this after it sees the delete. Otherwise the next full scan does it. Only the supplement is removed: the book and its other files stay. A file that Shisho cannot check, for example because of a permission error, is kept and the scan logs a warning.

After removing a missing supplement, the scan looks for supplements in that book's folder again. A supplement renamed while Shisho was not watching, or moved along with its book folder, is linked again at its new path. It comes back as a new file, so a display name you gave it is lost.

Managing Supplements

Changing file roles requires the Books Write permission and access to the book's library. See Users and Permissions.

warning

Demoting a main file clears its extracted format metadata, including its cover and chapters, but does not delete the media file from disk. Verify that the metadata can be recovered from the source or a backup before demoting. Leave the file as main if you only need to download it normally.

You can:

• Download a supplement.
• Give it a display name. The name you set replaces the filename as its label.
• Promote a supported supplement to a main file. In the file's Edit File dialog, set File Role to Main File and select Save Changes. Promotion triggers metadata extraction for that format.
• Demote a main file to a supplement. Set File Role to Supplement, then select Save Changes twice to confirm. Demotion clears its format-specific metadata.

Supplements are excluded from Kobo Sync and normal bulk-download selection. They are also excluded from surfaces that distribute main reading files, even if the supplement itself uses EPUB, AZW3, MOBI, CBZ, M4B, or PDF.

Troubleshooting

A File Was Not Discovered

Symptom: An expected supplement does not appear on the book.

Likely cause: It is outside the book directory, its root-level basename does not match, an exclusion pattern matched it, or Shisho already treats it as a main file.

Verify: Compare its location and basename with the discovery rules above, then review supplement_exclude_patterns and its current file role.

Fix: Move or rename the file to match the intended book, adjust the exclusion configuration if appropriate, and rescan.

An Unrelated File Was Attached

Symptom: A book shows a supplement that belongs elsewhere.

Likely cause: The book directory contains unrelated files or a root-level filename shares a broad prefix.

Verify: Check the candidate's directory and compare its basename with the main file's basename.

Fix: Separate books into distinct directories or rename root-level files to avoid the shared prefix, then rescan.

A PDF Has the Wrong Role

Symptom: A companion PDF stayed main, or a new PDF became a supplement unexpectedly.

Likely cause: Auto-demotion depends on creation time, directory placement, an exact configured basename, and an appropriate sibling.

Verify: Check whether the PDF was newly created in a directory-based book, then compare its exact basename with pdf_supplement_filenames and inspect the other recognized files in that directory tree.

Fix: Promote or demote the file manually for the current book. Adjust pdf_supplement_filenames only if the automatic rule should change for future files. See Libraries, Scanning, and File Organization, Configuration, and Troubleshooting.