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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
# 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.
## Quick Reference
- **Book data**: `data/books.json` (54 books)
- **Summaries**: `summaries/{id}.md` (one file per book, easy to edit)
- **Covers**: `images/covers/{id}.jpg`
- **Build command**: `node build.js`
## Key Points
- Summaries are markdown files in `summaries/` - edit directly, then run `node build.js`
- Always search by title+author first when looking for covers (not just ISBN)
- German books (Brandhorst, Reimer) often need alternative ISBN lookups
- Verify covers are real images (>10KB, JPEG format, not placeholders)
## 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 (id, title, author, year, format, isbn, language, coverLocal)
├── summaries/{id}.md # Book summaries as markdown files (easy to edit!)
├── 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"
}
```
**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
### 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. Add Summary
Create `summaries/{id}.md` with:
```markdown
# Book Title
Summary text goes here. Aim for 50-200 words describing the book's
plot, themes, and significance. This file is easy to edit manually.
```
**Finding summaries:**
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.
## Editing Summaries
Summaries are stored as individual markdown files in `summaries/`. To edit:
1. Open `summaries/{id}.md`
2. Edit the text (keep the `# Title` header)
3. Run `node build.js` to embed summaries into books.json
4. Refresh the page
This makes it easy to edit summaries in markdown without touching JSON directly.
## Building the Site
After editing any summary markdown files, run:
```bash
node build.js
```
This embeds all summaries from `summaries/*.md` into `data/books.json`, allowing the site to work offline without a server.
## 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)
|
