304 lines
15 KiB
Markdown
304 lines
15 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Sunday Comics is a Flask-based webcomic website with server-side rendering and client-side navigation. Comics are stored as individual YAML files in `data/comics/`, making them easy to manage without a database. Each comic gets its own file for clean organization and version control.
|
|
|
|
## Development Commands
|
|
|
|
**Run the development server:**
|
|
```bash
|
|
python app.py
|
|
```
|
|
Server runs on http://127.0.0.1:3000 by default.
|
|
|
|
**Enable debug mode:**
|
|
```bash
|
|
export DEBUG=True
|
|
python app.py
|
|
```
|
|
|
|
**Add a new comic:**
|
|
```bash
|
|
python scripts/add_comic.py
|
|
```
|
|
This creates a new YAML file in `data/comics/` with the next comic number and reasonable defaults. Edit the generated file to customize title, alt_text, author_note, etc.
|
|
|
|
**Add a new comic with markdown author note:**
|
|
```bash
|
|
python scripts/add_comic.py -m
|
|
```
|
|
This also creates a markdown file in `content/author_notes/` for the author note.
|
|
|
|
**Generate RSS feed:**
|
|
```bash
|
|
python scripts/generate_rss.py
|
|
```
|
|
Run this after adding/updating comics to regenerate `static/feed.rss`.
|
|
|
|
**Generate sitemap:**
|
|
```bash
|
|
python scripts/generate_sitemap.py
|
|
```
|
|
Run this after adding/updating comics to regenerate `static/sitemap.xml` for search engines.
|
|
|
|
**Publish comics (rebuild cache + RSS + sitemap):**
|
|
```bash
|
|
python scripts/publish_comic.py
|
|
```
|
|
Convenience script that rebuilds the cache and regenerates all static files in one command.
|
|
|
|
**Rebuild comics cache:**
|
|
```bash
|
|
python scripts/rebuild_cache.py
|
|
```
|
|
Force rebuild the comics cache from YAML files. Normally not needed (cache auto-invalidates).
|
|
|
|
## Architecture
|
|
|
|
### Data Layer: YAML Files in data/comics/
|
|
|
|
Comics are stored as individual YAML files in the `data/comics/` directory. The `data_loader.py` module automatically loads all `.yaml` files (except `TEMPLATE.yaml` and `README.yaml`), sorts them by comic number, and builds the `COMICS` list.
|
|
|
|
**Caching:** The data loader uses automatic caching to speed up subsequent loads:
|
|
- First load: Parses all YAML files, saves to `data/comics/.comics_cache.pkl`
|
|
- Subsequent loads: Reads from cache (~100x faster)
|
|
- Auto-invalidation: Cache rebuilds automatically when any YAML file is modified
|
|
- Cache can be disabled via environment variable: `DISABLE_COMIC_CACHE=true`
|
|
|
|
Performance with caching (1000 comics):
|
|
- Initial load: ~2-3 seconds (builds cache)
|
|
- Subsequent loads: ~0.01 seconds (uses cache)
|
|
- Scripts (RSS, sitemap): All share the same cache file on disk
|
|
|
|
**File structure:**
|
|
- `data/comics/001.yaml` - Comic #1
|
|
- `data/comics/002.yaml` - Comic #2
|
|
- `data/comics/003.yaml` - Comic #3
|
|
- `data/comics/TEMPLATE.yaml` - Template for new comics (ignored by loader)
|
|
- `data/comics/README.md` - Documentation for comic files
|
|
|
|
**Adding a new comic:**
|
|
1. Use `python scripts/add_comic.py` to auto-generate the next comic file
|
|
2. OR manually copy `TEMPLATE.yaml` and rename it
|
|
3. Edit the YAML file to set comic properties
|
|
|
|
Each comic YAML file contains:
|
|
- `number` (required): Sequential comic number
|
|
- `filename` (required): Image filename in `static/images/comics/` OR list of filenames for multi-image comics (webtoon style)
|
|
- `date` (required): Publication date in YYYY-MM-DD format
|
|
- `alt_text` (required): Accessibility text OR list of alt texts (one per image for multi-image comics)
|
|
- `title` (optional): Comic title (defaults to "#X" if absent)
|
|
- `author_note` (optional): Plain text note
|
|
- `author_note_md` (optional): Markdown file for author note (just filename like "2025-01-01.md" looks in `content/author_notes/`, or path like "special/note.md" relative to `content/`). Takes precedence over `author_note`.
|
|
- `full_width` (optional): Override global FULL_WIDTH_DEFAULT setting
|
|
- `plain` (optional): Override global PLAIN_DEFAULT setting (hides header/border)
|
|
- `section` (optional): Section/chapter title (e.g., "Chapter 1: Origins"). Add to first comic of a new section.
|
|
|
|
**Multi-image comics (webtoon style) in YAML:**
|
|
```yaml
|
|
filename:
|
|
- page1.png
|
|
- page2.png
|
|
- page3.png
|
|
alt_text:
|
|
- "Description 1"
|
|
- "Description 2"
|
|
- "Description 3"
|
|
```
|
|
- Set `filename` to a list of image filenames
|
|
- Set `alt_text` to either a single string (applies to all images) or a list matching each image
|
|
- If `alt_text` is a list but doesn't match `filename` length, a warning is logged
|
|
- Images display vertically with seamless stacking (no gaps)
|
|
- First image loads immediately; subsequent images lazy-load as user scrolls
|
|
- No click-through navigation on multi-image comics (use navigation buttons instead)
|
|
|
|
Global configuration in `comics_data.py`:
|
|
- `COMIC_NAME`: Your comic/website name
|
|
- `COPYRIGHT_NAME`: Name to display in copyright notice (defaults to COMIC_NAME if not set)
|
|
- `FULL_WIDTH_DEFAULT`: Set to True to make all comics full-width by default
|
|
- `PLAIN_DEFAULT`: Set to True to hide header/remove borders by default
|
|
- `ARCHIVE_FULL_WIDTH`: Set to True to make archive page full-width with 4 columns
|
|
- `SECTIONS_ENABLED`: Set to True to enable section headers on archive page (uses `section` field from comics)
|
|
- `HEADER_IMAGE`: Path relative to `static/images/` for site header image (set to None to disable)
|
|
- `FOOTER_IMAGE`: Path relative to `static/images/` for site footer image (set to None to disable)
|
|
- `BANNER_IMAGE`: Path relative to `static/images/` for shareable banner (set to None to hide "Link to Us" section)
|
|
- `COMPACT_FOOTER`: Display footer in compact single-line mode
|
|
- `USE_COMIC_NAV_ICONS`: Set to True to use icon images for comic navigation buttons instead of text (requires icons in `static/images/icons/`)
|
|
- `USE_HEADER_NAV_ICONS`: Set to True to display icons next to main header navigation text (uses alert.png, archive.png, info.png)
|
|
- `USE_FOOTER_SOCIAL_ICONS`: Set to True to use icons instead of text for footer social links (uses instagram.png, youtube.png, mail.png, alert.png)
|
|
- `NEWSLETTER_ENABLED`: Set to True to show newsletter section in footer
|
|
- `SOCIAL_INSTAGRAM`: Instagram URL (set to None to hide)
|
|
- `SOCIAL_YOUTUBE`: YouTube URL (set to None to hide)
|
|
- `SOCIAL_EMAIL`: Email mailto link (set to None to hide)
|
|
|
|
### Markdown Support
|
|
|
|
**Author Notes:** Add `author_note_md` field to comic entries with a filename (e.g., `"2025-01-01.md"`) or path relative to `content/` (e.g., `"special/note.md"`). Just a filename looks in `content/author_notes/`. The markdown content is rendered as HTML and takes precedence over the plain text `author_note` field.
|
|
|
|
**About Page:** The `/about` route renders `content/about.md` as HTML using the markdown library.
|
|
|
|
### Flask Application: app.py
|
|
|
|
**Core Functions:**
|
|
- `enrich_comic(comic)`: Adds computed properties (full_width, plain, formatted_date, author_note from markdown)
|
|
- `get_comic_by_number(number)`: Retrieves and enriches a comic by number
|
|
- `get_latest_comic()`: Returns the last comic in the COMICS list
|
|
- `format_comic_date(date_str)`: Converts YYYY-MM-DD to "Day name, Month name day, year"
|
|
- `get_author_note_from_file(filename)`: Loads markdown author note from file. Filename alone looks in `content/author_notes/`, paths are relative to `content/`.
|
|
- `group_comics_by_section(comics_list)`: Groups comics by section based on `section` field. Returns list of (section_title, comics) tuples.
|
|
|
|
**Routes:**
|
|
- `/` - Latest comic (index.html)
|
|
- `/comic/<id>` - Specific comic viewer (comic.html)
|
|
- `/archive` - Grid of all comics, newest first (archive.html)
|
|
- `/about` - Renders markdown from content/about.md (page.html)
|
|
- `/api/comics` - JSON array of all comics
|
|
- `/api/comics/<id>` - JSON for a specific comic
|
|
|
|
### Client-Side Navigation: static/js/comic-nav.js
|
|
|
|
Provides SPA-like navigation without page reloads:
|
|
- Fetches comics from `/api/comics/<id>`
|
|
- Updates DOM with `displayComic(comic)` function
|
|
- Handles navigation buttons and image click-through
|
|
- Uses History API to maintain proper URLs and browser back/forward
|
|
- Shows/hides header based on plain mode
|
|
- Adjusts container for full_width mode
|
|
- Updates author notes dynamically (plain text only; markdown rendering requires page reload)
|
|
|
|
**Note:** Client-side navigation displays author notes as plain text. Markdown author notes only render properly on initial page load (server-side).
|
|
|
|
### Templates
|
|
|
|
Built with Jinja2, extending `base.html`:
|
|
- `base.html`: Contains navigation header, footer, metadata tags (Open Graph, Twitter Cards)
|
|
- `index.html` & `comic.html`: Display comics with navigation buttons
|
|
- `archive.html`: Grid layout with thumbnails from `static/images/thumbs/`
|
|
- `page.html`: Generic template for markdown content (used by /about)
|
|
|
|
Global context variables injected into all templates:
|
|
- `comic_name`: Site/comic name from `comics_data.py`
|
|
- `copyright_name`: Copyright name from `comics_data.py` (defaults to `comic_name` if not set)
|
|
- `current_year`: Current year (auto-generated from system time)
|
|
- `header_image`: Site header image path from `comics_data.py`
|
|
- `footer_image`: Site footer image path from `comics_data.py`
|
|
- `banner_image`: Shareable banner image path from `comics_data.py`
|
|
- `compact_footer`: Boolean for footer style from `comics_data.py`
|
|
- `use_comic_nav_icons`: Boolean for comic navigation icons from `comics_data.py`
|
|
- `use_header_nav_icons`: Boolean for main header navigation icons from `comics_data.py`
|
|
- `use_footer_social_icons`: Boolean for footer social link icons from `comics_data.py`
|
|
- `newsletter_enabled`: Boolean to show/hide newsletter section from `comics_data.py`
|
|
- `social_instagram`: Instagram URL from `comics_data.py`
|
|
- `social_youtube`: YouTube URL from `comics_data.py`
|
|
- `social_email`: Email link from `comics_data.py`
|
|
|
|
## Static Assets
|
|
|
|
- `static/images/comics/`: Full-size comic images
|
|
- `static/images/thumbs/`: Thumbnails for archive page (optional, same filename as comic)
|
|
- `static/images/icons/`: Navigation icons (first.png, previous.png, next.png, latest.png) used when `USE_ICON_NAV` is True
|
|
- `static/images/`: Header images and other site graphics
|
|
- `static/feed.rss`: Generated RSS feed (run `scripts/generate_rss.py`)
|
|
- `static/sitemap.xml`: Generated sitemap (run `scripts/generate_sitemap.py`)
|
|
|
|
## Important Implementation Details
|
|
|
|
1. **Comic loading**: The `data_loader.py` module scans `data/comics/` for `.yaml` files, loads them, validates required fields, and sorts by comic number. TEMPLATE.yaml and README.yaml are automatically ignored. Results are cached to `.comics_cache.pkl` for performance.
|
|
|
|
2. **Comic ordering**: COMICS list order (determined by the `number` field in each YAML file) determines comic sequence. Last item is the "latest" comic.
|
|
|
|
3. **Enrichment pattern**: Always use `enrich_comic()` before passing comics to templates or APIs. This adds computed properties like `full_width`, `plain`, and `formatted_date`.
|
|
|
|
4. **Date formatting**: The `format_comic_date()` function uses `%d` with lstrip('0') for cross-platform compatibility (not all systems support `%-d`).
|
|
|
|
5. **Author notes hierarchy**: If `author_note_md` field is specified, the markdown file is loaded and rendered as HTML, taking precedence over the plain text `author_note` field. When markdown is used, `author_note_is_html` is set to True.
|
|
|
|
6. **Settings cascade**: Global settings (FULL_WIDTH_DEFAULT, PLAIN_DEFAULT) apply unless overridden per-comic with `full_width` or `plain` keys in the YAML file.
|
|
|
|
7. **Navigation state**: Client-side navigation reads `data-total-comics` and `data-comic-number` from the `.comic-container` element to manage button states.
|
|
|
|
8. **Comic icon navigation**: When `USE_COMIC_NAV_ICONS` is True, templates use `.btn-icon-nav` class with icon images instead of text buttons. JavaScript automatically detects icon mode and applies appropriate classes. Disabled icons have reduced opacity (0.3).
|
|
|
|
9. **Archive sections**: When `SECTIONS_ENABLED` is True, comics with a `section` field will start a new section on the archive page. Only add the `section` field to the first comic of each new section. All subsequent comics belong to that section until a new `section` field is encountered.
|
|
|
|
10. **YAML validation**: The data loader validates each comic file and logs warnings for missing required fields (`number`, `filename`, `date`, `alt_text`). Invalid files are skipped.
|
|
|
|
## Production Deployment
|
|
|
|
The app uses Flask's development server by default. For production:
|
|
|
|
**Recommended: Docker**
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
**Alternative: Gunicorn**
|
|
```bash
|
|
pip install gunicorn
|
|
export SECRET_KEY="$(python -c 'import secrets; print(secrets.token_hex(32))')"
|
|
export DEBUG=False
|
|
gunicorn app:app --bind 0.0.0.0:3000 --workers 4
|
|
```
|
|
|
|
Environment variables:
|
|
- `SECRET_KEY`: Flask secret key (generate with `secrets.token_hex(32)`)
|
|
- `PORT`: Server port (default: 3000)
|
|
- `DEBUG`: Debug mode (default: False)
|
|
|
|
## Accessibility Implementation
|
|
|
|
Sunday Comics follows WCAG 2.1 Level AA guidelines. When modifying the site, maintain these accessibility features:
|
|
|
|
### Keyboard Navigation
|
|
- **Focus indicators**: All interactive elements have visible 3px outlines when focused (defined in `static/css/style.css`)
|
|
- **Skip to main content**: First focusable element on every page, appears at top when focused
|
|
- **Keyboard shortcuts**: Arrow keys (Left/Right), Home, End for comic navigation (handled in `static/js/comic-nav.js`)
|
|
- **Focus management**: After navigation, focus programmatically moves to `#comic-image-focus` element
|
|
|
|
### Screen Reader Support
|
|
- **ARIA live region**: `#comic-announcer` element announces comic changes with `aria-live="polite"`
|
|
- **ARIA labels**: All icon buttons have descriptive `aria-label` attributes
|
|
- **ARIA disabled**: Disabled navigation buttons include `aria-disabled="true"`
|
|
- **Empty alt text**: Decorative icons (next to text labels) use `alt=""` to prevent redundant announcements
|
|
- **Clickable images**: Links wrapping comic images have `aria-label="Click to view next comic"`
|
|
|
|
### Semantic HTML
|
|
- Proper heading hierarchy (h1 → h2 → h3)
|
|
- `lang="en"` on html element
|
|
- Semantic elements: `<header>`, `<nav>`, `<main>`, `<footer>`
|
|
- `tabindex="-1"` on programmatically focusable elements (not in tab order)
|
|
|
|
### CSS Accessibility
|
|
- `.sr-only` class: Hides content visually but keeps it accessible to screen readers
|
|
- `.skip-to-main` class: Positioned off-screen until focused, then slides into view
|
|
- Focus styles use `outline` property (never remove without replacement)
|
|
- Disabled buttons use both color and opacity for visibility
|
|
|
|
### JavaScript Accessibility
|
|
The `comic-nav.js` file handles:
|
|
1. **Announcements**: Updates `#comic-announcer` text content on navigation
|
|
2. **Focus**: Calls `.focus()` on `#comic-image-focus` after loading comic
|
|
3. **ARIA attributes**: Dynamically adds/removes `aria-disabled` on navigation buttons
|
|
4. **Boundary feedback**: Announces "Already at first/latest comic" at navigation limits
|
|
|
|
### Maintaining Accessibility
|
|
When adding features:
|
|
- Ensure all images have meaningful alt text
|
|
- Test with keyboard only (no mouse)
|
|
- Verify focus indicators are visible
|
|
- Check ARIA labels on icon buttons
|
|
- Test with screen readers when possible (VoiceOver, NVDA)
|
|
- Maintain semantic HTML structure
|
|
|
|
## Testing Approach
|
|
|
|
No test suite currently exists. When adding tests, consider:
|
|
- Comic retrieval and enrichment logic
|
|
- API endpoint responses
|
|
- Date formatting edge cases
|
|
- Markdown rendering for author notes and about page
|
|
- Accessibility: keyboard navigation, ARIA attributes, focus management
|