1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
# Sci-Fi Book Showcase - Agent Instructions
This is a static HTML page showcasing a sci-fi book collection. It works fully offline with all assets stored locally.
## Project Structure
```
/home/paul/git/scifi/
├── index.html # Main page
├── css/styles.css # Styling
├── js/app.js # Client-side logic (filtering, modals)
├── data/books.json # Book metadata (THE source of truth)
├── images/covers/{id}.jpg # Cover images (named by book ID)
├── input.json # Original source data (reference only)
└── scripts/ # Utility scripts (not part of site)
```
## Adding a New Book
### 1. Update `data/books.json`
Add a new entry to the `books` array:
```json
{
"id": 55,
"title": "Book Title",
"author": "Author Name",
"year": 2024,
"format": "Paperback",
"isbn": "9781234567890",
"language": "en",
"coverLocal": "images/covers/55.jpg",
"summary": "A compelling summary of the book...",
"summarySource": "manual"
}
```
**Fields:**
- `id`: Unique integer (use next available number)
- `title`: Display title (use German title for German books)
- `author`: Author name
- `year`: Publication year
- `format`: One of "Paperback", "eBook", "Audiobook"
- `isbn`: ISBN-13 preferred (used for cover lookups)
- `language`: "en" or "de"
- `coverLocal`: Path to local cover image
- `summary`: Book description (aim for 50-200 words)
- `summarySource`: Where summary came from ("OpenLibrary", "Wikipedia", "manual", etc.)
### 2. Add Cover Image
Save cover as `images/covers/{id}.jpg`
**Finding covers (in order of preference):**
1. **OpenLibrary by title/author** (best for finding covers not indexed by ISBN):
```
https://openlibrary.org/search.json?q={title}+{author}&limit=5
```
Then get cover: `https://covers.openlibrary.org/b/id/{cover_i}-L.jpg`
2. **OpenLibrary by ISBN**:
```
https://covers.openlibrary.org/b/isbn/{isbn}-L.jpg
```
3. **Google Books API**:
```
https://www.googleapis.com/books/v1/volumes?q=isbn:{isbn}
```
Extract `volumeInfo.imageLinks.thumbnail`, replace `zoom=1` with `zoom=2` or `zoom=3`
**Cover quality checks:**
- File size should be > 10KB (smaller = likely placeholder)
- Should be JPEG (check with `file` command)
- Resolution should be ~300x500 or better
- MD5 hash `c96309220b9cbd205c36d879d09a3647` = Google Books placeholder (reject it)
### 3. Finding Summaries
**Sources (in order of preference):**
1. **OpenLibrary Works API**:
```
https://openlibrary.org/isbn/{isbn}.json → get works[0].key
https://openlibrary.org{works_key}.json → get description
```
2. **Wikipedia API** (good for well-known books):
```
https://{lang}.wikipedia.org/w/api.php?action=query&list=search&srsearch={title}+{author}&format=json
https://{lang}.wikipedia.org/w/api.php?action=query&prop=extracts&exintro=true&explaintext=true&pageids={pageid}&format=json
```
Use `de.wikipedia.org` for German books, `en.wikipedia.org` for English.
3. **Manual**: Write a summary based on publisher descriptions or reviews.
## Common Issues
### German books missing covers
German publishers (Piper, Heyne) often aren't in OpenLibrary. Try:
- Search by title+author instead of ISBN
- Try multiple ISBN editions (paperback, ebook, audiobook)
- Check if book exists under slightly different title
### Placeholder images
Google Books returns a 15567-byte placeholder for missing covers. Always verify:
```bash
file images/covers/{id}.jpg # Should show JPEG, decent resolution
ls -la images/covers/{id}.jpg # Should be > 10KB
```
### Cover is wrong book
Search by title+author can return wrong matches. Verify the cover matches by checking:
- Author name on cover
- Title spelling
- Publisher logo matches expected publisher
## Utility Scripts (in `scripts/`)
These are development utilities, not part of the deployed site:
- `download-assets.js` - Bulk download covers and summaries
- `fix-missing-covers.js` - Try alternative ISBNs for missing covers
- `fix-placeholders.js` - Replace placeholder images
- `fetch-all-summaries.js` - Fetch summaries from Wikipedia
- `sync-summaries.js` - Copy summaries from input.json to books.json
## Testing
```bash
cd /home/paul/git/scifi
python -m http.server 8000
# Open http://localhost:8000
```
Verify:
- All books display in grid
- Covers load (no broken images)
- Click opens modal with summary
- Filters work (author, format, search)
|
