Configuration Examples

Ready-to-use configurations for common use cases.

Western Comics (Komga-compatible)

Simple folder structure where each series has its own folder.

/library/
  ├── Batman/
  │   ├── Batman #001.cbz
  │   └── Batman #002.cbz
  └── Spider-Man/
      └── Spider-Man #001.cbz

{
  "series_strategy": "series_volume",
  "book_strategy": "filename"
}

This is the default configuration.

Chapter-based Manga

Manga organized with volume subfolders containing individual chapters.

/library/
  └── One Piece/
      ├── Volume 01/
      │   ├── Chapter 001.cbz
      │   └── Chapter 002.cbz
      └── Volume 02/
          └── Chapter 003.cbz

{
  "series_strategy": "series_volume_chapter",
  "book_strategy": "smart"
}

Flat Collection with Bracket Naming

All files in one folder with series names in brackets.

/library/
  ├── [One Piece] v01.cbz
  ├── [One Piece] v02.cbz
  ├── [Naruto] Chapter 001.cbz
  └── [Bleach] Vol 01.cbz

{
  "series_strategy": "flat",
  "series_config": {
    "filename_patterns": ["\\[([^\\]]+)\\]"],
    "require_metadata": false
  },
  "book_strategy": "filename"
}

Flat Collection with Metadata

All files in one folder, relying on embedded metadata for series detection.

/library/
  ├── file1.cbz  (ComicInfo.xml has Series="One Piece")
  ├── file2.cbz  (ComicInfo.xml has Series="One Piece")
  └── file3.cbz  (ComicInfo.xml has Series="Naruto")

{
  "series_strategy": "flat",
  "series_config": {
    "require_metadata": true
  },
  "book_strategy": "metadata_first"
}

Publisher-organized Comics

Comics organized by publisher, then series.

/library/
  ├── Marvel/
  │   ├── Spider-Man/
  │   │   └── Amazing Spider-Man #001.cbz
  │   └── X-Men/
  │       └── X-Men #001.cbz
  └── DC/
      ├── Batman/
      │   └── Batman #001.cbz
      └── Superman/
          └── Action Comics #001.cbz

{
  "series_strategy": "publisher_hierarchy",
  "series_config": {
    "skip_depth": 1,
    "store_skipped_as": "publisher"
  },
  "book_strategy": "filename"
}

Publisher + Year Hierarchy

Comics organized by publisher, then year, then series.

/library/
  ├── Marvel/
  │   ├── 2023/
  │   │   └── Spider-Man/
  │   │       └── Spider-Man #001.cbz
  │   └── 2024/
  │       └── X-Men/
  │           └── X-Men #001.cbz
  └── DC/
      └── 2024/
          └── Batman/
              └── Batman #001.cbz

{
  "series_strategy": "publisher_hierarchy",
  "series_config": {
    "skip_depth": 2,
    "store_skipped_as": "publisher"
  },
  "book_strategy": "filename"
}

Calibre Ebook Library

Direct import from a Calibre library folder.

/library/
  ├── Brandon Sanderson/
  │   ├── Mistborn (45)/
  │   │   ├── Mistborn - Brandon Sanderson.epub
  │   │   └── metadata.opf
  │   └── The Well of Ascension (46)/
  │       └── The Well of Ascension - Brandon Sanderson.epub
  └── George R. R. Martin/
      └── A Game of Thrones (208)/
          └── A Game Of Thrones.epub

{
  "series_strategy": "calibre",
  "series_config": {
    "strip_id_suffix": true,
    "series_mode": "from_metadata",
    "read_opf_metadata": true,
    "author_from_folder": true
  },
  "book_strategy": "metadata_first"
}

Calibre with Author-based Series

Group all books by the same author into a series.

{
  "series_strategy": "calibre",
  "series_config": {
    "strip_id_suffix": true,
    "series_mode": "by_author",
    "author_from_folder": true
  },
  "book_strategy": "metadata_first"
}

Custom: Scanlation Group Format

Files with scanlation group tags. The (?P<volume>\d+) and (?P<chapter>\d+) named groups populate the per-book volume/chapter fields, which feed the series count display and "behind by N" indicators.

/library/
  ├── [GroupName] One Piece v01 c001.cbz
  ├── [GroupName] One Piece v01 c002.cbz
  └── [GroupName] Naruto v01 c001.cbz

{
  "series_strategy": "flat",
  "series_config": {
    "filename_patterns": ["\\] ([^v]+?) v"]
  },
  "book_strategy": "custom",
  "book_config": {
    "pattern": "\\] (?P<series>.+?) v(?P<volume>\\d+) c(?P<chapter>\\d+(?:\\.\\d+)?)",
    "title_template": "{series} v.{volume} c.{chapter}",
    "fallback": "filename"
  }
}

The (?:\.\d+)? inside the chapter group makes fractional chapter numbers (c042.5) work for special chapters and side stories. Drop it if your library never uses fractional chapters.

Custom: TV-style Episode Numbering

Files with SxxExx or seasonXepisode format. Each season maps to a volume; each episode maps to a chapter.

/library/
  ├── Series Name - S01E01 - Episode Title.cbz
  ├── Series Name - S01E02 - Another Title.cbz
  └── Series Name - S02E01 - Season Two.cbz

{
  "series_strategy": "flat",
  "series_config": {
    "filename_patterns": ["^([^-]+) -"]
  },
  "book_strategy": "custom",
  "book_config": {
    "pattern": "^(?P<series>.+?) - S(?P<volume>\\d+)E(?P<chapter>\\d+) - (?P<title>.+)$",
    "title_template": "{title}",
    "fallback": "filename"
  }
}

Custom: Chapter-Only Library With Range Filenames

Some scanlation packs distribute chapter ranges as a single file (c001-005.cbz). Capture the first chapter of the range so the series's local_max_chapter aggregate stays correct.

/library/
  └── Series Name/
      ├── Series Name - c001-005.cbz
      ├── Series Name - c006-010.cbz
      └── Series Name - c011.cbz

{
  "series_strategy": "series_volume",
  "book_strategy": "custom",
  "book_config": {
    "pattern": "^(?P<series>.+?) - c(?P<chapter>\\d+(?:\\.\\d+)?)(?:-\\d+)?$",
    "title_template": "{series} c.{chapter}",
    "fallback": "filename"
  }
}

The (?:-\d+)? in the pattern matches and discards the optional -005 end-of-range portion so each book is classified by its starting chapter. No volume group means books are classified as chapter-only.

Custom: Volume-Of-Series + Issue Number

Western-comic-style filenames where each issue is also a volume's worth of standalone content (Series Vol.1 #5).

/library/
  ├── Saga Vol.1 #001.cbz
  ├── Saga Vol.1 #002.cbz
  └── Saga Vol.2 #001.cbz

{
  "series_strategy": "series_volume",
  "book_strategy": "custom",
  "book_config": {
    "pattern": "^(?P<series>.+?) Vol\\.(?P<volume>\\d+) #(?P<chapter>\\d+(?:\\.\\d+)?)",
    "title_template": "{series} v.{volume} #{chapter}",
    "fallback": "filename"
  }
}

This populates both volume and chapter per book, so the book detail page renders the combined Vol V · Ch C badge and the series detail header shows both totals when known.

Creating via API

Basic Creation

curl -X POST http://localhost:8080/api/v1/libraries \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Comics",
    "path": "/library/comics",
    "series_strategy": "series_volume",
    "book_strategy": "filename"
  }'

With Configuration

curl -X POST http://localhost:8080/api/v1/libraries \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Calibre Library",
    "path": "/library/calibre",
    "series_strategy": "calibre",
    "series_config": {
      "strip_id_suffix": true,
      "series_mode": "from_metadata"
    },
    "book_strategy": "metadata_first"
  }'

Preview Before Creating

curl -X POST http://localhost:8080/api/v1/libraries/preview-scan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/library/manga",
    "series_strategy": "series_volume_chapter"
  }'

Response:

{
  "detected_series": [
    {
      "name": "One Piece",
      "path": "/library/manga/One Piece",
      "book_count": 150,
      "sample_books": ["Chapter 001.cbz", "Chapter 002.cbz"]
    }
  ]
}

Troubleshooting

Series Not Grouped Correctly

Use Preview Scan to test before creating
Verify folder structure matches the strategy
For flat strategy, check filename patterns

Books Missing Numbers

Try smart or metadata_first book strategy
Add ComicInfo.xml to your files
Use custom book strategy with appropriate regex

Want to Change Strategy

Strategies are immutable. To change:

Delete the library (files stay on disk)
Create new library with desired strategy
Run scan

note

Read progress is lost when deleting a library.

Western Comics (Komga-compatible)​

Chapter-based Manga​

Flat Collection with Bracket Naming​

Flat Collection with Metadata​

Publisher-organized Comics​

Publisher + Year Hierarchy​

Calibre Ebook Library​

Calibre with Author-based Series​

Custom: Scanlation Group Format​

Custom: TV-style Episode Numbering​

Custom: Chapter-Only Library With Range Filenames​

Custom: Volume-Of-Series + Issue Number​

Creating via API​

Basic Creation​

With Configuration​

Preview Before Creating​

Troubleshooting​

Series Not Grouped Correctly​

Books Missing Numbers​

Want to Change Strategy​