## File Naming Patterns

Configure automatic file organization using metadata placeholders. Patterns are applied when uploading files, moving files within your library, and after metadata updates.

### Default File Naming Pattern

This pattern serves as the fallback when no library-specific override is configured.

Default Pattern
@if (defaultErrorMessage) {
{{ defaultErrorMessage }}
}
Preview: {{ generateDefaultPreview() }}

### Library-Specific Overrides

Define custom naming patterns for specific libraries. Leave empty to use the default pattern.

@for (library of libraries; track library.id) {
{{ library.name }}
Preview: {{ generateLibraryPreview(library) }}
}

### Available Placeholders

Use placeholders to dynamically insert book metadata into file names and folder paths. These will be replaced with actual values when uploading or moving files.

#### Available Placeholders

- `{{ '{title}' }}` – Book title
- `{{ '{subtitle}' }}` – Book subtitle
- `{{ '{authors}' }}` – Author(s)
- `{{ '{year}' }}` – Full year (e.g. 2025)
- `{{ '{series}' }}` – Series name
- `{{ '{seriesIndex}' }}` – Series index (e.g. 01)
- `{{ '{language}' }}` – Language code (e.g. en)
- `{{ '{publisher}' }}` – Publisher name
- `{{ '{isbn}' }}` – ISBN number
- `{{ '{currentFilename}' }}` Original file name (with extension)

#### Optional blocks

Surround parts of your pattern with angle brackets `{{ '{<...>}' }}`
to make them optional. If any placeholder inside the block has no value, the whole block is excluded.

Example:

`{{ '{<{seriesIndex} - >{title}' }}`

- `01 - Dune` (if `{{ '{seriesIndex}' }}` exists)
- `Dune` (if `{{ '{seriesIndex}' }}` is missing)

### Example Patterns & Output

See how different patterns work with sample book metadata and learn best practices for organizing your library.

#### Examples with Full Metadata

title: `The Name of the Wind` subtitle: `Special Edition` authors: `Patrick Rothfuss` series: `The Kingkiller Chronicle` seriesIndex: `01` year: `2007` currentFilename: `name_of_the_wind_original.epub`

Basic pattern: `{{ '{authors} - {title}' }}`

Output: `Patrick Rothfuss - The Name of the Wind.epub`

Pattern with punctuation: `{{ '{title}: {series}' }}`

Output: `The Name of the Wind: The Kingkiller Chronicle.epub`

Series in folder path: `{{ '{authors}/{series}/{seriesIndex} - {title}' }}`

Output: `Patrick Rothfuss/The Kingkiller Chronicle/01 - The Name of the Wind.epub`

Folder only: `{{ '{title}/' }}`

Output: `/The Name of the Wind/name_of_the_wind_original.epub`

Absolute path: `{{ '/{authors}/{title}' }}`

Output: `/Patrick Rothfuss/The Name of the Wind.epub`

Reuse original filename in path: `{{ '{authors}/{series}/{currentFilename}' }}`

Output: `Patrick Rothfuss/The Kingkiller Chronicle/name_of_the_wind_original.epub`

Title + Subtitle: `{{ '{title}: {subtitle}' }}`

Output: `The Name of the Wind: The Kingkiller Chronicle: Day One.epub`

#### Examples with Missing Optional Fields

title: `Project Hail Mary` subtitle: `(not provided)` authors: `Andy Weir` year: `2021` series: `(not provided)` seriesIndex: `(not provided)` currentFilename: `project_hail_mary_final.epub`

Pattern with optional blocks: `{{ '{authors}/<{series}/><{seriesIndex}. >{title}< ({year})>' }}`

Output: `Andy Weir/Project Hail Mary (2021).epub`

Fallback with seriesIndex and dash: `{{ '<{seriesIndex}. >{title}< - {authors}>' }}`

Output: `Project Hail Mary - Andy Weir.epub`

Brackets & punctuation fallback: `{{ '<[{series}] >{title} - {authors}' }}`

Output: `Project Hail Mary - Andy Weir.epub`

Series + punctuation fallback: `{{ '<{series}: >{title} by {authors}' }}`

Output: `Project Hail Mary by Andy Weir.epub`

Use original filename with year suffix: `{{ '{authors}/{year}__{currentFilename}' }}`

Output: `Andy Weir/2021__project_hail_mary_final.epub`

Title + Subtitle fallback: `{{ '{title} <: {subtitle}>' }}`

Output: `Project Hail Mary.epub`