diff --git a/README.md b/README.md index 4fa2135..c76e524 100644 --- a/README.md +++ b/README.md @@ -50,22 +50,150 @@ grawlix --username "user@example.com" --password "SuperSecretPassword" **Config file example** ```toml -[sources.name] +# Global settings +write_metadata_to_epub = true +output = "~/ebooks/{series}/{index} - {title}.{ext}" + +[sources.storytel] username = "user@example.com" password = "SuperSecretPassword" ``` -Config file should be placed in `~/.config/grawlix/grawlix.toml` + +Config file should be placed in: +- Linux: `~/.config/grawlix/grawlix.toml` +- macOS: `~/Library/Application Support/grawlix/grawlix.toml` +- Windows: `%LOCALAPPDATA%\jo1gi\grawlix\grawlix.toml` ### Cookies Some sources can be authenticated with Netscape cookie files. I use -[this extension](https://github,com/rotemdan/ExportCookies) to export my +[this extension](https://github.com/rotemdan/ExportCookies) to export my cookies from my browser. Cookies can be placed in current dir as `cookies.txt` or be given with the -`--cookie` argument. +`--cookies` argument. + +## Configuration + +### Global Settings + +The following settings can be added to your config file (before any `[sources.*]` sections): + +| Setting | Type | Description | Example | +|---------|------|-------------|---------| +| `write_metadata_to_epub` | boolean | Automatically write metadata to EPUB files (supports Storytel and Nextory) | `true` or `false` | +| `output` | string | Default output path template (supports `~`, environment variables, and template variables) | `"~/ebooks/{title}.{ext}"` | + +### Output Templates + +The `output` setting supports template variables that are replaced with book metadata: + +| Variable | Description | Example | +|----------|-------------|---------| +| `{title}` | Book title | "The Witcher" | +| `{series}` | Series name | "The Witcher Saga" | +| `{index}` | Series index/number | "1" | +| `{authors}` | Authors (semicolon-separated) | "Andrzej Sapkowski" | +| `{publisher}` | Publisher name | "Orbit" | +| `{language}` | Language code | "en" | +| `{release_date}` | Release date | "2020-01-15" | +| `{source}` | Source/service name | "Storytel", "Marvel", etc. | +| `{ext}` | File extension (auto-detected from source) | "epub" | + +**Example templates:** +```toml +# Simple (auto-detect format) +output = "~/books/{title}.{ext}" + +# Force EPUB format +output = "~/books/{title}.epub" + +# Organized by source +output = "~/books/{source}/{title}.{ext}" + +# Organized by series (auto-detect format) +output = "~/books/{series}/{index} - {title}.{ext}" + +# Force EPUB with series organization +output = "~/books/{series}/{index} - {title}.epub" + +# Organized by source and series +output = "~/books/{source}/{series}/{index} - {title}.epub" +``` + +**Note:** The file extension in your template determines the output format: +- Use `.epub` to force EPUB output +- Use `.cbz` to force CBZ (comic book) output +- Use `{ext}` to auto-detect the best format for each source + +**Path expansion:** +- `~` expands to home directory +- Environment variables work: `$HOME` (Unix) or `%USERPROFILE%` (Windows) +- Absolute paths: `/path/to/books` or `C:\Books` +- Relative paths: `downloads/{title}.{ext}` (relative to current directory) ## Download books + To download a book run: ```shell grawlix [options] ``` + +### Command Line Options + +| Option | Short | Description | +|--------|-------|-------------| +| `--version` | `-v` | Show version number | +| `--file ` | `-f` | File with URLs (one per line) | +| `--username ` | `-u` | Username for authentication | +| `--password ` | `-p` | Password for authentication | +| `--library ` | | Library name (for sources that require it) | +| `--cookies ` | `-c` | Path to Netscape cookie file | +| `--output