File Structure

The scanner uses folder structure as its primary grouping signal — a subfolder becomes a series, the files inside become its issues. Metadata embedded in the files or their names enriches that grouping but does not override it.

The two patterns

Series in a subfolder (recommended)

Place all issues of a series in one folder named after the series. The folder name becomes the series name.

/comics/
└── Batman (1940-2011)/
    ├── Batman 001 (1940).cbz
    ├── Batman 002 (1940).cbz
    └── Batman 500 (1993).cbz

Stashix strips common year and date suffixes from the folder name and stores them as start_year / end_year on the series record. Supported patterns:

Standalone books at the library root

A file placed directly in the library root (not inside any subfolder) is imported as a standalone book with no series.

/books/
├── The Complete Persepolis.cbz   ← standalone
└── Watchmen.cbz                  ← standalone

Standalone folders

You can also designate a folder as a standalone container — every file inside is treated as a standalone book. Configure additional folder names in Admin → Libraries → Standalone folders. The built-in defaults are:

• one-shot
• one shot
• oneshot

/comics/
└── one-shot/
    ├── Batman Noel.cbz      ← standalone
    └── Superman Smashes.cbz ← standalone

Optional: publisher folder

If your library has a three-level hierarchy (publisher → series → issues), Stashix infers the publisher from the grandparent folder for new books:

/comics/
└── DC Comics/           ← inferred publisher
    └── Batman (1940)/
        ├── Batman 001.cbz
        └── Batman 002.cbz

The publisher is only inferred at import time for new books. Renaming the folder later does not automatically update existing books.

Metadata precedence

Within a single file, Stashix merges metadata from multiple sources. The order of precedence, highest first:

1. Sidecar XML — <filename>.xml next to the file (MetronInfo or ComicInfo format)
2. Embedded MetronInfo.xml — inside the archive
3. Embedded ComicInfo.xml — inside the archive (or the PDF info-dict for .pdf)
4. Filename parsing — series name, issue number, volume, year

Later sources fill in gaps; earlier sources win on any field they provide. Exception: ComicInfo.Year beats a year derived from MetronInfo’s cover-date fields.

Filename patterns

When no embedded metadata is present, Stashix extracts the series name, issue number, volume, and year from the filename. The parser tries the following patterns in order and stops at the first match:

Noise tags — (Digital), (HQ), (Webrip), (c2c), (Retail), (FIXED), (v2), etc. — are stripped before parsing. The (of N) suffix is also removed.

Tips and common mistakes

Do keep each series in its own folder, named consistently. The scanner detects folder renames by comparing file hashes, so your reading progress survives renaming a series folder.

Do not mix multiple series in one folder. Stashix uses one folder = one series, so all files in the same directory end up in the same series.

Do not nest series inside each other more than one level below the library root unless you use the publisher pattern. Deep nesting is supported by the recursive walker but only one folder level above the file becomes the series.

Do use a sidecar XML (Batman 001.xml) when you want reliable metadata that overrides filename guesses. The ComicInfo.xml or MetronInfo.xml format is both accepted.