feat: v1.2.0-rc.2 - Media display fixes and feed enhancements
## Added - Feed Media Enhancement with Media RSS namespace support - RSS enclosure, media:content, media:thumbnail elements - JSON Feed image field for first image - ADR-059: Full feed media standardization roadmap ## Fixed - Media display on homepage (was only showing on note pages) - Responsive image sizing with CSS constraints - Caption display (now alt text only, not visible) - Logging correlation ID crash in non-request contexts ## Documentation - Feed media design documents and implementation reports - Media display fixes design and validation reports - Updated ROADMAP with v1.3.0/v1.4.0 media plans 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
334
docs/design/feed-media-handling-options.md
Normal file
334
docs/design/feed-media-handling-options.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# Feed Media Handling: Architecture Options Analysis
|
||||
|
||||
**Date**: 2025-12-09
|
||||
**Author**: StarPunk Architect
|
||||
**Status**: Proposed
|
||||
**Related**: ADR-057, Q24, Q27, Q28
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Analysis of the current feed output reveals that RSS 2.0 lacks proper media enclosure elements, while ATOM and JSON Feed have partial implementations. This document proposes three options for fixing media handling across all feed formats.
|
||||
|
||||
## Current State Analysis
|
||||
|
||||
### RSS Feed (Problem)
|
||||
```xml
|
||||
<item>
|
||||
<title>Test</title>
|
||||
<link>http://localhost:8000/note/with-a-test-slug</link>
|
||||
<description><div class="media"><img src="..." alt="Just some dude" /></div><p>Test</p></description>
|
||||
<guid isPermaLink="true">http://localhost:8000/note/with-a-test-slug</guid>
|
||||
<pubDate>Fri, 28 Nov 2025 23:23:13 +0000</pubDate>
|
||||
</item>
|
||||
```
|
||||
|
||||
**Issues Identified**:
|
||||
1. No `<enclosure>` element for the image
|
||||
2. Image is only embedded as HTML in description
|
||||
3. Many feed readers (Feedly, Reeder) won't display the image prominently
|
||||
4. No `media:content` or `media:thumbnail` elements
|
||||
|
||||
### ATOM Feed (Partial)
|
||||
```xml
|
||||
<entry>
|
||||
<link rel="enclosure" type="image/jpeg" href="..." length="1796654"/>
|
||||
<content type="html">...</content>
|
||||
</entry>
|
||||
```
|
||||
|
||||
**Status**: Correctly includes enclosure link. ATOM implementation is acceptable.
|
||||
|
||||
### JSON Feed (Partial)
|
||||
```json
|
||||
{
|
||||
"attachments": [
|
||||
{
|
||||
"url": "...",
|
||||
"mime_type": "image/jpeg",
|
||||
"size_in_bytes": 1796654,
|
||||
"title": "Just some dude"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Issues Identified**:
|
||||
1. Has attachments array (correct per JSON Feed 1.1 spec)
|
||||
2. Missing top-level `image` field for featured image
|
||||
3. Some readers use `image` for thumbnail display
|
||||
|
||||
## Standards Research Summary
|
||||
|
||||
### RSS 2.0 Specification
|
||||
Per the [RSS 2.0 Specification](https://www.rssboard.org/rss-specification):
|
||||
- `<enclosure>` element requires: `url`, `length`, `type`
|
||||
- Only ONE enclosure per item is officially supported (though many readers accept multiple)
|
||||
- Images in `<description>` are fallback, not primary
|
||||
|
||||
### Media RSS (MRSS) Extension
|
||||
Per the [Media RSS Specification](https://www.rssboard.org/media-rss):
|
||||
- Namespace: `http://search.yahoo.com/mrss/`
|
||||
- `<media:content>` for primary media with `medium="image"`
|
||||
- `<media:thumbnail>` for preview images
|
||||
- Provides richer metadata than basic enclosure
|
||||
|
||||
### JSON Feed 1.1 Specification
|
||||
Per the [JSON Feed 1.1 spec](https://jsonfeed.org/version/1.1):
|
||||
- `image` field: URL of the main/featured image (for preview/thumbnail)
|
||||
- `attachments` array: Related resources (files, media)
|
||||
- Both can coexist - `image` for display, `attachments` for download
|
||||
|
||||
### Feed Reader Compatibility Notes
|
||||
|
||||
| Reader | Enclosure | media:content | HTML Images | Notes |
|
||||
|--------|-----------|---------------|-------------|-------|
|
||||
| Feedly | Good | Excellent | Fallback | Prefers media:thumbnail |
|
||||
| NetNewsWire | Good | Good | Yes | Displays HTML images inline |
|
||||
| Reeder | Good | Good | Yes | Uses enclosure for preview |
|
||||
| Inoreader | Good | Excellent | Yes | Full MRSS support |
|
||||
| FreshRSS | Good | Good | Yes | Displays all sources |
|
||||
| Feedbin | Good | Good | Yes | Clean HTML rendering |
|
||||
|
||||
---
|
||||
|
||||
## Option 1: RSS Enclosure Only (Minimal)
|
||||
|
||||
### Description
|
||||
Add the standard RSS `<enclosure>` element to RSS feeds for the first image only, keeping HTML images in description as fallback.
|
||||
|
||||
### Implementation Changes
|
||||
|
||||
**File**: `/home/phil/Projects/starpunk/starpunk/feeds/rss.py`
|
||||
|
||||
```python
|
||||
# In generate_rss() after setting description
|
||||
if hasattr(note, 'media') and note.media:
|
||||
first_media = note.media[0]
|
||||
media_url = f"{site_url}/media/{first_media['path']}"
|
||||
fe.enclosure(
|
||||
url=media_url,
|
||||
length=str(first_media.get('size', 0)),
|
||||
type=first_media.get('mime_type', 'image/jpeg')
|
||||
)
|
||||
```
|
||||
|
||||
**File**: `/home/phil/Projects/starpunk/starpunk/feeds/rss.py` (streaming version)
|
||||
|
||||
```python
|
||||
# In generate_rss_streaming() item generation
|
||||
if hasattr(note, 'media') and note.media:
|
||||
first_media = note.media[0]
|
||||
media_url = f"{site_url}/media/{first_media['path']}"
|
||||
mime_type = first_media.get('mime_type', 'image/jpeg')
|
||||
size = first_media.get('size', 0)
|
||||
yield f' <enclosure url="{_escape_xml(media_url)}" length="{size}" type="{mime_type}"/>\n'
|
||||
```
|
||||
|
||||
### Pros
|
||||
1. **Simplest implementation** - Single element addition
|
||||
2. **Spec-compliant** - Pure RSS 2.0, no extensions
|
||||
3. **Wide compatibility** - All RSS readers support enclosure
|
||||
4. **Low risk** - Minimal code changes
|
||||
|
||||
### Cons
|
||||
1. **Single image only** - RSS spec ambiguous about multiple enclosures
|
||||
2. **No thumbnail metadata** - Readers must use full-size image
|
||||
3. **No alt text/caption** - Enclosure has no description attribute
|
||||
4. **Less prominent display** - Some readers treat enclosure as "download" not "display"
|
||||
|
||||
### Complexity Score: 2/10
|
||||
|
||||
---
|
||||
|
||||
## Option 2: RSS + Media RSS Extension (Recommended)
|
||||
|
||||
### Description
|
||||
Add both standard `<enclosure>` and Media RSS (`media:content`, `media:thumbnail`) elements. This provides maximum compatibility across modern feed readers while supporting multiple images and richer metadata.
|
||||
|
||||
### Implementation Changes
|
||||
|
||||
**File**: `/home/phil/Projects/starpunk/starpunk/feeds/rss.py`
|
||||
|
||||
Add namespace to feed:
|
||||
```python
|
||||
# Register Media RSS namespace
|
||||
fg.register_extension('media', 'http://search.yahoo.com/mrss/')
|
||||
```
|
||||
|
||||
Add media elements per item:
|
||||
```python
|
||||
if hasattr(note, 'media') and note.media:
|
||||
for i, media_item in enumerate(note.media):
|
||||
media_url = f"{site_url}/media/{media_item['path']}"
|
||||
mime_type = media_item.get('mime_type', 'image/jpeg')
|
||||
size = media_item.get('size', 0)
|
||||
caption = media_item.get('caption', '')
|
||||
|
||||
# First image: use as enclosure AND thumbnail
|
||||
if i == 0:
|
||||
fe.enclosure(url=media_url, length=str(size), type=mime_type)
|
||||
# Would need custom extension handling for media:thumbnail
|
||||
|
||||
# All images: add as media:content
|
||||
# Note: feedgen doesn't support media:* natively
|
||||
# May need to use custom XML generation or switch to streaming
|
||||
```
|
||||
|
||||
**File**: `/home/phil/Projects/starpunk/starpunk/feeds/rss.py` (streaming - cleaner approach)
|
||||
|
||||
```python
|
||||
# In XML header
|
||||
yield '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/">\n'
|
||||
|
||||
# In item generation
|
||||
if hasattr(note, 'media') and note.media:
|
||||
for i, media_item in enumerate(note.media):
|
||||
media_url = f"{site_url}/media/{media_item['path']}"
|
||||
mime_type = media_item.get('mime_type', 'image/jpeg')
|
||||
size = media_item.get('size', 0)
|
||||
caption = _escape_xml(media_item.get('caption', ''))
|
||||
|
||||
# First image as enclosure (RSS 2.0 standard)
|
||||
if i == 0:
|
||||
yield f' <enclosure url="{_escape_xml(media_url)}" length="{size}" type="{mime_type}"/>\n'
|
||||
# Also as thumbnail for readers that prefer it
|
||||
yield f' <media:thumbnail url="{_escape_xml(media_url)}"/>\n'
|
||||
|
||||
# All images as media:content
|
||||
yield f' <media:content url="{_escape_xml(media_url)}" type="{mime_type}" fileSize="{size}" medium="image"'
|
||||
if caption:
|
||||
yield f'>\n'
|
||||
yield f' <media:description type="plain">{caption}</media:description>\n'
|
||||
yield f' </media:content>\n'
|
||||
else:
|
||||
yield f'/>\n'
|
||||
```
|
||||
|
||||
### Pros
|
||||
1. **Maximum compatibility** - Works with all modern readers
|
||||
2. **Multiple images supported** - Media RSS handles arrays naturally
|
||||
3. **Rich metadata** - Captions, dimensions, alt text possible
|
||||
4. **Prominent display** - Readers using media:thumbnail show images well
|
||||
5. **Graceful degradation** - Falls back to enclosure for older readers
|
||||
|
||||
### Cons
|
||||
1. **More complexity** - Multiple elements to generate
|
||||
2. **Namespace required** - Adds xmlns declaration
|
||||
3. **feedgen limitations** - May need streaming approach for full control
|
||||
4. **Spec sprawl** - Using RSS 2.0 + MRSS together
|
||||
|
||||
### Complexity Score: 5/10
|
||||
|
||||
---
|
||||
|
||||
## Option 3: Full Standardization (All Formats)
|
||||
|
||||
### Description
|
||||
Comprehensive update to all three feed formats ensuring consistent media handling with both structured elements AND HTML content, plus adding the `image` field to JSON Feed items.
|
||||
|
||||
### Implementation Changes
|
||||
|
||||
**RSS** (same as Option 2):
|
||||
- Add `<enclosure>` for first image
|
||||
- Add `<media:content>` for all images
|
||||
- Add `<media:thumbnail>` for first image
|
||||
- Keep HTML images in description
|
||||
|
||||
**ATOM** (already mostly correct):
|
||||
- Current implementation is good
|
||||
- Consider adding `<media:thumbnail>` via MRSS namespace
|
||||
|
||||
**JSON Feed**:
|
||||
```python
|
||||
# In _build_item_object()
|
||||
def _build_item_object(site_url: str, note: Note) -> Dict[str, Any]:
|
||||
# ... existing code ...
|
||||
|
||||
# Add featured image (first image) at item level
|
||||
if hasattr(note, 'media') and note.media:
|
||||
first_media = note.media[0]
|
||||
media_url = f"{site_url}/media/{first_media['path']}"
|
||||
item["image"] = media_url # Top-level image field
|
||||
|
||||
# Attachments array (existing code)
|
||||
attachments = []
|
||||
for media_item in note.media:
|
||||
# ... existing attachment building ...
|
||||
item["attachments"] = attachments
|
||||
```
|
||||
|
||||
### Content Strategy Decision
|
||||
|
||||
**Should HTML content include images?**
|
||||
|
||||
Yes, always include images in HTML content (`description`, `content_html`) as well as in structured elements. Rationale:
|
||||
1. Some readers only render HTML, ignoring enclosures
|
||||
2. Ensures consistent display across all reader types
|
||||
3. ADR-057 and Q24 already mandate this approach
|
||||
4. IndieWeb convention supports redundant markup
|
||||
|
||||
### Pros
|
||||
1. **Complete solution** - All formats fully supported
|
||||
2. **Maximum reader compatibility** - Covers all reader behaviors
|
||||
3. **Consistent experience** - Users see images regardless of reader
|
||||
4. **Future-proof** - Handles any new reader implementations
|
||||
|
||||
### Cons
|
||||
1. **Most complex** - Changes to all three feed generators
|
||||
2. **Redundant data** - Images in multiple places (intentional)
|
||||
3. **Larger feed size** - More XML/JSON to transmit
|
||||
4. **Testing burden** - Must validate all three formats
|
||||
|
||||
### Complexity Score: 7/10
|
||||
|
||||
---
|
||||
|
||||
## Recommendation
|
||||
|
||||
**I recommend Option 2: RSS + Media RSS Extension** for the following reasons:
|
||||
|
||||
### Rationale
|
||||
|
||||
1. **Addresses the actual problem**: The user reported RSS as the problem format; ATOM and JSON Feed are working acceptably.
|
||||
|
||||
2. **Best compatibility/complexity ratio**: Media RSS is widely supported by Feedly, Inoreader, and other major readers without excessive implementation burden.
|
||||
|
||||
3. **Multiple image support**: Unlike Option 1, this handles the 2-4 image case that ADR-057 designed for.
|
||||
|
||||
4. **Caption preservation**: Media RSS supports `<media:description>` which preserves alt text/captions.
|
||||
|
||||
5. **Minimal JSON Feed changes**: JSON Feed only needs the `image` field addition (small change with good impact).
|
||||
|
||||
### Implementation Priority
|
||||
|
||||
1. **Phase 1**: Add `<enclosure>` to RSS (Option 1) - Immediate fix, 1 hour
|
||||
2. **Phase 2**: Add Media RSS namespace and elements - Enhanced fix, 2-3 hours
|
||||
3. **Phase 3**: Add `image` field to JSON Feed items - Polish, 30 minutes
|
||||
|
||||
### Testing Validation
|
||||
|
||||
After implementation, validate with:
|
||||
1. [W3C Feed Validator](https://validator.w3.org/feed/) - RSS/ATOM compliance
|
||||
2. [JSON Feed Validator](https://validator.jsonfeed.org/) - JSON Feed compliance
|
||||
3. Manual testing in: Feedly, NetNewsWire, Reeder, Inoreader, FreshRSS
|
||||
|
||||
---
|
||||
|
||||
## Decision Required
|
||||
|
||||
The architect recommends **Option 2** but requests stakeholder input on:
|
||||
|
||||
1. Is multiple image support in RSS essential, or is first-image-only acceptable?
|
||||
2. Are there specific feed readers that must be supported?
|
||||
3. What is the timeline for this fix?
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [RSS 2.0 Specification](https://www.rssboard.org/rss-specification)
|
||||
- [Media RSS Specification](https://www.rssboard.org/media-rss)
|
||||
- [JSON Feed 1.1](https://www.jsonfeed.org/version/1.1/)
|
||||
- [ATOM RFC 4287](https://tools.ietf.org/html/rfc4287)
|
||||
- ADR-057: Media Attachment Model
|
||||
- Q24-Q28: v1.2.0 Developer Q&A (Feed Integration)
|
||||
424
docs/design/feed-media-option2-design.md
Normal file
424
docs/design/feed-media-option2-design.md
Normal file
@@ -0,0 +1,424 @@
|
||||
# Feed Media Enhancement Design: Option 2 (RSS + Media RSS Extension)
|
||||
|
||||
## Overview
|
||||
|
||||
This design document specifies the implementation of Option 2 for feed media support: adding Media RSS namespace elements to RSS feeds and the `image` field to JSON Feed items. This provides improved feed reader compatibility for notes with attached images.
|
||||
|
||||
**Target Version**: v1.2.x
|
||||
**Estimated Effort**: 4-6 hours
|
||||
**Prerequisites**: Media attachment model implemented (ADR-057)
|
||||
|
||||
## Current State
|
||||
|
||||
### RSS Feed (`starpunk/feeds/rss.py`)
|
||||
- Embeds media as `<img>` tags within the `<description>` CDATA section
|
||||
- Uses feedgen library for RSS 2.0 generation
|
||||
- No `<enclosure>` elements
|
||||
- No Media RSS namespace
|
||||
|
||||
### JSON Feed (`starpunk/feeds/json_feed.py`)
|
||||
- Includes media in `attachments` array (per JSON Feed 1.1 spec)
|
||||
- Includes media as `<img>` tags in `content_html`
|
||||
- No top-level `image` field for items
|
||||
|
||||
### Note Model
|
||||
- Media accessed via `note.media` property (list of dicts)
|
||||
- Each media item has: `path`, `mime_type`, `size`, `caption` (optional)
|
||||
|
||||
## Design Goals
|
||||
|
||||
1. **Standards Compliance**: Follow Media RSS spec and JSON Feed 1.1 spec
|
||||
2. **Backward Compatibility**: Keep existing HTML embedding for universal reader support
|
||||
3. **Feed Reader Optimization**: Add structured metadata for enhanced display
|
||||
4. **Minimal Changes**: Modify only feed generation, no database changes
|
||||
|
||||
## Files to Modify
|
||||
|
||||
### 1. `starpunk/feeds/rss.py`
|
||||
|
||||
**Changes Required**:
|
||||
|
||||
#### A. Add Media RSS Namespace to Feed Generator
|
||||
|
||||
Location: `generate_rss()` function and `generate_rss_streaming()` function
|
||||
|
||||
```python
|
||||
# Add namespace registration before generating XML
|
||||
# For feedgen-based generation:
|
||||
fg.load_extension('media', rss=True) # feedgen has built-in media extension
|
||||
|
||||
# For streaming generation, add to opening RSS tag:
|
||||
'<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/">\n'
|
||||
```
|
||||
|
||||
#### B. Add RSS `<enclosure>` Element (First Image Only)
|
||||
|
||||
Per RSS 2.0 spec, only ONE enclosure per item is allowed. Use the first image.
|
||||
|
||||
```python
|
||||
# In item generation, after setting description:
|
||||
if hasattr(note, 'media') and note.media:
|
||||
first_media = note.media[0]
|
||||
media_url = f"{site_url}/media/{first_media['path']}"
|
||||
fe.enclosure(
|
||||
url=media_url,
|
||||
length=str(first_media.get('size', 0)),
|
||||
type=first_media.get('mime_type', 'image/jpeg')
|
||||
)
|
||||
```
|
||||
|
||||
#### C. Add Media RSS Elements (All Images)
|
||||
|
||||
For each image, add `<media:content>` and optional `<media:description>`:
|
||||
|
||||
```python
|
||||
# Using feedgen's media extension:
|
||||
for media_item in note.media:
|
||||
media_url = f"{site_url}/media/{media_item['path']}"
|
||||
|
||||
# Add media:content
|
||||
fe.media.content({
|
||||
'url': media_url,
|
||||
'type': media_item.get('mime_type', 'image/jpeg'),
|
||||
'medium': 'image',
|
||||
'fileSize': str(media_item.get('size', 0))
|
||||
})
|
||||
|
||||
# Add media:description if caption exists
|
||||
if media_item.get('caption'):
|
||||
fe.media.description(media_item['caption'], type='plain')
|
||||
|
||||
# Add media:thumbnail for first image
|
||||
if note.media:
|
||||
first_media = note.media[0]
|
||||
fe.media.thumbnail({
|
||||
'url': f"{site_url}/media/{first_media['path']}"
|
||||
})
|
||||
```
|
||||
|
||||
#### D. Expected XML Output Structure
|
||||
|
||||
For an item with 2 images:
|
||||
|
||||
```xml
|
||||
<item>
|
||||
<title>My Note Title</title>
|
||||
<link>https://example.com/note/my-slug</link>
|
||||
<guid isPermaLink="true">https://example.com/note/my-slug</guid>
|
||||
<pubDate>Mon, 09 Dec 2024 12:00:00 +0000</pubDate>
|
||||
|
||||
<!-- Standard RSS enclosure (first image only) -->
|
||||
<enclosure url="https://example.com/media/2024/12/image1.jpg"
|
||||
length="245760"
|
||||
type="image/jpeg"/>
|
||||
|
||||
<!-- Media RSS elements (all images) -->
|
||||
<media:content url="https://example.com/media/2024/12/image1.jpg"
|
||||
type="image/jpeg"
|
||||
medium="image"
|
||||
fileSize="245760"/>
|
||||
<media:content url="https://example.com/media/2024/12/image2.jpg"
|
||||
type="image/jpeg"
|
||||
medium="image"
|
||||
fileSize="198432"/>
|
||||
|
||||
<!-- Thumbnail (first image) -->
|
||||
<media:thumbnail url="https://example.com/media/2024/12/image1.jpg"/>
|
||||
|
||||
<!-- Caption if present -->
|
||||
<media:description type="plain">Photo from today's hike</media:description>
|
||||
|
||||
<!-- Description with embedded HTML (for legacy readers) -->
|
||||
<description><![CDATA[
|
||||
<div class="media">
|
||||
<img src="https://example.com/media/2024/12/image1.jpg" alt="Photo from today's hike" />
|
||||
<img src="https://example.com/media/2024/12/image2.jpg" alt="" />
|
||||
</div>
|
||||
<p>Note content here...</p>
|
||||
]]></description>
|
||||
</item>
|
||||
```
|
||||
|
||||
### 2. `starpunk/feeds/json_feed.py`
|
||||
|
||||
**Changes Required**:
|
||||
|
||||
#### A. Add `image` Field to Item Objects
|
||||
|
||||
Per JSON Feed 1.1 spec, `image` is "the URL of the main image for the item."
|
||||
|
||||
Location: `_build_item_object()` function
|
||||
|
||||
```python
|
||||
def _build_item_object(site_url: str, note: Note) -> Dict[str, Any]:
|
||||
# ... existing code ...
|
||||
|
||||
# Add image field (URL of first/main image)
|
||||
# Per JSON Feed 1.1: "the URL of the main image for the item"
|
||||
if hasattr(note, 'media') and note.media:
|
||||
first_media = note.media[0]
|
||||
item["image"] = f"{site_url}/media/{first_media['path']}"
|
||||
|
||||
# ... rest of existing code (content_html, attachments, etc.) ...
|
||||
```
|
||||
|
||||
#### B. Expected JSON Output Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "https://example.com/note/my-slug",
|
||||
"url": "https://example.com/note/my-slug",
|
||||
"title": "My Note Title",
|
||||
"date_published": "2024-12-09T12:00:00Z",
|
||||
|
||||
"image": "https://example.com/media/2024/12/image1.jpg",
|
||||
|
||||
"content_html": "<div class=\"media\"><img src=\"https://example.com/media/2024/12/image1.jpg\" alt=\"Photo from today's hike\" /><img src=\"https://example.com/media/2024/12/image2.jpg\" alt=\"\" /></div><p>Note content here...</p>",
|
||||
|
||||
"attachments": [
|
||||
{
|
||||
"url": "https://example.com/media/2024/12/image1.jpg",
|
||||
"mime_type": "image/jpeg",
|
||||
"title": "Photo from today's hike",
|
||||
"size_in_bytes": 245760
|
||||
},
|
||||
{
|
||||
"url": "https://example.com/media/2024/12/image2.jpg",
|
||||
"mime_type": "image/jpeg",
|
||||
"size_in_bytes": 198432
|
||||
}
|
||||
],
|
||||
|
||||
"_starpunk": {
|
||||
"permalink_path": "/note/my-slug",
|
||||
"word_count": 42
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### RSS Implementation: feedgen vs Manual Streaming
|
||||
|
||||
**For `generate_rss()` (feedgen-based)**:
|
||||
|
||||
The feedgen library has a media extension. Check if it's available:
|
||||
|
||||
```python
|
||||
# Test if feedgen supports media extension
|
||||
from feedgen.ext.media import MediaExtension
|
||||
|
||||
# If supported, use:
|
||||
fg.register_extension('media', MediaExtension, rss=True)
|
||||
```
|
||||
|
||||
If feedgen's media extension is insufficient, consider manual XML injection after feedgen generates the base XML.
|
||||
|
||||
**For `generate_rss_streaming()` (manual XML)**:
|
||||
|
||||
Modify the streaming generator to include media elements. This requires:
|
||||
|
||||
1. Update the opening RSS tag to include media namespace
|
||||
2. Add `<enclosure>` element after `<pubDate>`
|
||||
3. Add `<media:content>` elements for each image
|
||||
4. Add `<media:thumbnail>` for first image
|
||||
5. Add `<media:description>` if caption exists
|
||||
|
||||
### JSON Feed Implementation
|
||||
|
||||
Straightforward addition in `_build_item_object()`:
|
||||
|
||||
```python
|
||||
# Add image field if media exists
|
||||
if hasattr(note, 'media') and note.media:
|
||||
first_media = note.media[0]
|
||||
item["image"] = f"{site_url}/media/{first_media['path']}"
|
||||
```
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
### Unit Tests to Add/Modify
|
||||
|
||||
**File**: `tests/test_feeds_rss.py` (create or extend)
|
||||
|
||||
```python
|
||||
def test_rss_enclosure_for_note_with_media():
|
||||
"""RSS item should include enclosure element for first image."""
|
||||
# Create note with media
|
||||
# Generate RSS
|
||||
# Parse XML, verify <enclosure> present with correct attributes
|
||||
|
||||
def test_rss_media_content_for_all_images():
|
||||
"""RSS item should include media:content for each image."""
|
||||
# Create note with 2 images
|
||||
# Generate RSS
|
||||
# Parse XML, verify 2 <media:content> elements
|
||||
|
||||
def test_rss_media_thumbnail_for_first_image():
|
||||
"""RSS item should include media:thumbnail for first image."""
|
||||
# Create note with media
|
||||
# Generate RSS
|
||||
# Parse XML, verify <media:thumbnail> present
|
||||
|
||||
def test_rss_media_description_for_caption():
|
||||
"""RSS item should include media:description if caption exists."""
|
||||
# Create note with captioned image
|
||||
# Generate RSS
|
||||
# Parse XML, verify <media:description> present
|
||||
|
||||
def test_rss_no_media_elements_without_attachments():
|
||||
"""RSS item without media should have no media elements."""
|
||||
# Create note without media
|
||||
# Generate RSS
|
||||
# Parse XML, verify no enclosure or media:* elements
|
||||
|
||||
def test_rss_namespace_declaration():
|
||||
"""RSS feed should declare media namespace."""
|
||||
# Generate any RSS feed
|
||||
# Verify xmlns:media attribute in root element
|
||||
```
|
||||
|
||||
**File**: `tests/test_feeds_json.py` (create or extend)
|
||||
|
||||
```python
|
||||
def test_json_feed_image_field_for_note_with_media():
|
||||
"""JSON Feed item should include image field for first image."""
|
||||
# Create note with media
|
||||
# Generate JSON feed
|
||||
# Parse JSON, verify "image" field present with correct URL
|
||||
|
||||
def test_json_feed_no_image_field_without_media():
|
||||
"""JSON Feed item without media should not have image field."""
|
||||
# Create note without media
|
||||
# Generate JSON feed
|
||||
# Parse JSON, verify "image" field not present
|
||||
|
||||
def test_json_feed_image_uses_first_media():
|
||||
"""JSON Feed image field should use first media item URL."""
|
||||
# Create note with 3 images
|
||||
# Generate JSON feed
|
||||
# Verify "image" URL matches first image path
|
||||
```
|
||||
|
||||
### Feed Validation Tests
|
||||
|
||||
**Manual Validation** (document in test plan):
|
||||
|
||||
1. **W3C Feed Validator**: https://validator.w3.org/feed/
|
||||
- Submit generated RSS feed
|
||||
- Verify no errors for media:* elements
|
||||
- Note: Validator may warn about unknown extensions (acceptable)
|
||||
|
||||
2. **Feed Reader Testing**:
|
||||
- Feedly: Verify images display in article preview
|
||||
- NetNewsWire: Check media thumbnail in list view
|
||||
- Feedbin: Test image extraction
|
||||
- RSS.app: Verify enclosure handling
|
||||
|
||||
3. **JSON Feed Validator**: Use online JSON Feed validator
|
||||
- Verify `image` field accepted
|
||||
- Verify `attachments` array valid
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```python
|
||||
def test_rss_route_with_media_notes(client, app):
|
||||
"""GET /feed.xml with media notes returns valid RSS with media elements."""
|
||||
# Create test notes with media
|
||||
# Request /feed.xml
|
||||
# Verify response contains media namespace and elements
|
||||
|
||||
def test_json_route_with_media_notes(client, app):
|
||||
"""GET /feed.json with media notes returns JSON with image fields."""
|
||||
# Create test notes with media
|
||||
# Request /feed.json
|
||||
# Verify response contains image fields
|
||||
```
|
||||
|
||||
## Reference Documentation
|
||||
|
||||
### Media RSS Specification
|
||||
- **URL**: https://www.rssboard.org/media-rss
|
||||
- **Key Elements Used**:
|
||||
- `media:content` - Primary media reference
|
||||
- `media:thumbnail` - Preview image
|
||||
- `media:description` - Caption text
|
||||
|
||||
### JSON Feed 1.1 Specification
|
||||
- **URL**: https://jsonfeed.org/version/1.1/
|
||||
- **Key Fields Used**:
|
||||
- `image` (item level) - "the URL of the main image for the item"
|
||||
- `attachments` - Array of attachment objects (already implemented)
|
||||
|
||||
### RSS 2.0 Enclosure Specification
|
||||
- **URL**: https://www.rssboard.org/rss-specification#ltenclosuregtSubelementOfLtitemgt
|
||||
- **Constraint**: Only ONE enclosure per item allowed
|
||||
- **Required Attributes**: `url`, `length`, `type`
|
||||
|
||||
## Feed Reader Compatibility Notes
|
||||
|
||||
### Media RSS Support
|
||||
|
||||
| Reader | media:content | media:thumbnail | enclosure |
|
||||
|--------|---------------|-----------------|-----------|
|
||||
| Feedly | Yes | Yes | Yes |
|
||||
| Inoreader | Yes | Yes | Yes |
|
||||
| NetNewsWire | Partial | Yes | Yes |
|
||||
| Feedbin | Yes | Yes | Yes |
|
||||
| RSS.app | Yes | Yes | Yes |
|
||||
| The Old Reader | Yes | Partial | Yes |
|
||||
|
||||
### JSON Feed Image Support
|
||||
|
||||
| Reader | image field | attachments |
|
||||
|--------|-------------|-------------|
|
||||
| Feedly | Yes | Yes |
|
||||
| NetNewsWire | Yes | Yes |
|
||||
| Reeder | Yes | Yes |
|
||||
| Feedbin | Yes | Yes |
|
||||
|
||||
**Note**: The HTML-embedded images in `description`/`content_html` serve as fallback for readers that don't support Media RSS or JSON Feed attachments.
|
||||
|
||||
## Rollout Plan
|
||||
|
||||
1. **Implement RSS Changes**
|
||||
- Add namespace declaration
|
||||
- Add enclosure element
|
||||
- Add media:content elements
|
||||
- Add media:thumbnail
|
||||
- Add media:description for captions
|
||||
|
||||
2. **Implement JSON Feed Changes**
|
||||
- Add image field to item builder
|
||||
|
||||
3. **Add Tests**
|
||||
- Unit tests for both feed types
|
||||
- Integration tests for routes
|
||||
|
||||
4. **Manual Validation**
|
||||
- Test with W3C validator
|
||||
- Test in 3+ feed readers
|
||||
|
||||
5. **Deploy**
|
||||
- Release as part of v1.2.x
|
||||
|
||||
## Future Considerations (Option 3)
|
||||
|
||||
This design explicitly does NOT include:
|
||||
- Multiple image sizes/thumbnails (deferred to ADR-059)
|
||||
- Video support (deferred to v1.4.0)
|
||||
- Audio/podcast support (deferred to v1.3.0+)
|
||||
- Full Media RSS attribute set (width, height, duration)
|
||||
|
||||
These are documented in ADR-059: Full Feed Media Standardization for future releases.
|
||||
|
||||
## Summary of Changes
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `starpunk/feeds/rss.py` | Add media namespace, enclosure, media:content, media:thumbnail, media:description |
|
||||
| `starpunk/feeds/json_feed.py` | Add `image` field to items with media |
|
||||
| `tests/test_feeds_rss.py` | Add 6 new test cases for media elements |
|
||||
| `tests/test_feeds_json.py` | Add 3 new test cases for image field |
|
||||
|
||||
**Total Estimated Changes**: ~100-150 lines of new code + ~100 lines of tests
|
||||
311
docs/design/media-display-fixes.md
Normal file
311
docs/design/media-display-fixes.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# Media Display Fixes - Architectural Design
|
||||
|
||||
## Status
|
||||
Active
|
||||
|
||||
## Problem Statement
|
||||
Three issues with current media display implementation:
|
||||
1. **Images too large** - No CSS constraints on image dimensions
|
||||
2. **Captions visible** - Currently showing figcaption, should use alt text only
|
||||
3. **Images missing on homepage** - Media not fetched or displayed in index.html
|
||||
|
||||
## Root Cause Analysis
|
||||
|
||||
### Issue 1: Images Too Large
|
||||
The current CSS (`/static/css/style.css`) has NO styles for:
|
||||
- `.note-media` container
|
||||
- `.media-item` figure elements
|
||||
- `.u-photo` images
|
||||
- Responsive image constraints
|
||||
|
||||
Images display at their native dimensions, which can break layouts.
|
||||
|
||||
### Issue 2: Captions Visible
|
||||
Template (`note.html` lines 25-27) explicitly renders figcaption:
|
||||
```html
|
||||
{% if item.caption %}
|
||||
<figcaption>{{ item.caption }}</figcaption>
|
||||
{% endif %}
|
||||
```
|
||||
This violates the social media pattern where captions are for accessibility (alt text) only.
|
||||
|
||||
### Issue 3: Missing Homepage Media
|
||||
The index route (`public.py` line 231) doesn't fetch media:
|
||||
```python
|
||||
notes = list_notes(published_only=True, limit=20)
|
||||
```
|
||||
Compare to the note route (lines 263-267) which DOES fetch media.
|
||||
|
||||
## Architectural Solution
|
||||
|
||||
### Design Principles
|
||||
1. **Consistency**: Same media display logic on all pages
|
||||
2. **Responsive**: Images adapt to viewport and container
|
||||
3. **Accessible**: Alt text for screen readers, no visible captions
|
||||
4. **Performance**: Lazy loading for below-fold images
|
||||
5. **Standards**: Proper Microformats2 markup maintained
|
||||
|
||||
### Component Architecture
|
||||
|
||||
#### 1. CSS Media Display System
|
||||
Create responsive, constrained image display with grid layouts:
|
||||
|
||||
```css
|
||||
/* Media container styles */
|
||||
.note-media {
|
||||
margin-bottom: var(--spacing-md);
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
/* Single image - full width */
|
||||
.note-media:has(.media-item:only-child) {
|
||||
max-width: 100%;
|
||||
}
|
||||
|
||||
.note-media:has(.media-item:only-child) .media-item {
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
/* Two images - side by side */
|
||||
.note-media:has(.media-item:nth-child(2):last-child) {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(2, 1fr);
|
||||
gap: var(--spacing-sm);
|
||||
}
|
||||
|
||||
/* Three or four images - grid */
|
||||
.note-media:has(.media-item:nth-child(3)),
|
||||
.note-media:has(.media-item:nth-child(4)) {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(2, 1fr);
|
||||
gap: var(--spacing-sm);
|
||||
}
|
||||
|
||||
/* Media item wrapper */
|
||||
.media-item {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
background: var(--color-bg-alt);
|
||||
border-radius: var(--border-radius);
|
||||
overflow: hidden;
|
||||
aspect-ratio: 1 / 1; /* Instagram-style square crop */
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
/* Image constraints */
|
||||
.media-item img,
|
||||
.u-photo {
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
object-fit: cover; /* Crop to fill container */
|
||||
display: block;
|
||||
}
|
||||
|
||||
/* For single images, allow natural aspect ratio */
|
||||
.note-media:has(.media-item:only-child) .media-item {
|
||||
aspect-ratio: auto;
|
||||
max-height: 500px; /* Prevent extremely tall images */
|
||||
}
|
||||
|
||||
.note-media:has(.media-item:only-child) .media-item img {
|
||||
object-fit: contain; /* Show full image for singles */
|
||||
width: 100%;
|
||||
height: auto;
|
||||
max-height: 500px;
|
||||
}
|
||||
|
||||
/* Remove figcaption from display */
|
||||
.media-item figcaption {
|
||||
display: none; /* Captions are for alt text only */
|
||||
}
|
||||
|
||||
/* Mobile responsive adjustments */
|
||||
@media (max-width: 767px) {
|
||||
/* Stack images vertically on small screens */
|
||||
.note-media:has(.media-item:nth-child(2):last-child) {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
.media-item {
|
||||
aspect-ratio: 16 / 9; /* Wider aspect on mobile */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Template Refactoring
|
||||
|
||||
Create a reusable macro for media display to ensure consistency:
|
||||
|
||||
**New template partial: `templates/partials/media.html`**
|
||||
```jinja2
|
||||
{# Reusable media display macro #}
|
||||
{% macro display_media(media_items) %}
|
||||
{% if media_items %}
|
||||
<div class="note-media">
|
||||
{% for item in media_items %}
|
||||
<figure class="media-item">
|
||||
<img src="{{ url_for('public.media_file', path=item.path) }}"
|
||||
alt="{{ item.caption or 'Image' }}"
|
||||
class="u-photo"
|
||||
loading="lazy">
|
||||
{# No figcaption - caption is for alt text only #}
|
||||
</figure>
|
||||
{% endfor %}
|
||||
</div>
|
||||
{% endif %}
|
||||
{% endmacro %}
|
||||
```
|
||||
|
||||
**Updated `note.html`** (lines 16-31):
|
||||
```jinja2
|
||||
{# Import media macro #}
|
||||
{% from "partials/media.html" import display_media %}
|
||||
|
||||
{# Media display at TOP (v1.2.0 Phase 3, per ADR-057) #}
|
||||
{{ display_media(note.media) }}
|
||||
```
|
||||
|
||||
**Updated `index.html`** (after line 26, before e-content):
|
||||
```jinja2
|
||||
{# Import media macro at top of file #}
|
||||
{% from "partials/media.html" import display_media %}
|
||||
|
||||
{# In the note loop, after the title check #}
|
||||
{% if has_explicit_title %}
|
||||
<h3 class="p-name">{{ note.title }}</h3>
|
||||
{% endif %}
|
||||
|
||||
{# Media preview (if available) #}
|
||||
{{ display_media(note.media) }}
|
||||
|
||||
{# e-content: note content (preview) #}
|
||||
<div class="e-content">
|
||||
```
|
||||
|
||||
#### 3. Route Handler Updates
|
||||
|
||||
Update the index route to fetch media for each note:
|
||||
|
||||
**`starpunk/routes/public.py`** (lines 219-233):
|
||||
```python
|
||||
@bp.route("/")
|
||||
def index():
|
||||
"""
|
||||
Homepage displaying recent published notes with media
|
||||
|
||||
Returns:
|
||||
Rendered homepage template with note list including media
|
||||
|
||||
Template: templates/index.html
|
||||
Microformats: h-feed containing h-entry items with u-photo
|
||||
"""
|
||||
from starpunk.media import get_note_media
|
||||
|
||||
# Get recent published notes (limit 20)
|
||||
notes = list_notes(published_only=True, limit=20)
|
||||
|
||||
# Attach media to each note for display
|
||||
for note in notes:
|
||||
media = get_note_media(note.id)
|
||||
# Use object.__setattr__ since Note is frozen dataclass
|
||||
object.__setattr__(note, 'media', media)
|
||||
|
||||
return render_template("index.html", notes=notes)
|
||||
```
|
||||
|
||||
### Implementation Guidelines
|
||||
|
||||
#### Phase 1: CSS Foundation
|
||||
1. Add media display styles to `/static/css/style.css`
|
||||
2. Test with 1, 2, 3, and 4 image layouts
|
||||
3. Verify responsive behavior on mobile/tablet/desktop
|
||||
4. Ensure images don't overflow containers
|
||||
|
||||
#### Phase 2: Template Refactoring
|
||||
1. Create `templates/partials/` directory if not exists
|
||||
2. Create `media.html` with display macro
|
||||
3. Update `note.html` to use macro
|
||||
4. Update `index.html` to import and use macro
|
||||
5. Remove figcaption rendering completely
|
||||
|
||||
#### Phase 3: Route Updates
|
||||
1. Import `get_note_media` in index route
|
||||
2. Fetch media for each note in loop
|
||||
3. Attach media using `object.__setattr__`
|
||||
4. Verify media passes to template
|
||||
|
||||
### Testing Checklist
|
||||
|
||||
#### Visual Tests
|
||||
- [ ] Single image displays at reasonable size
|
||||
- [ ] Two images display side-by-side
|
||||
- [ ] Three images display in 2x2 grid (one empty)
|
||||
- [ ] Four images display in 2x2 grid
|
||||
- [ ] Images maintain aspect ratio appropriately
|
||||
- [ ] No layout overflow on any screen size
|
||||
- [ ] Captions not visible (alt text only)
|
||||
|
||||
#### Functional Tests
|
||||
- [ ] Homepage shows media for notes
|
||||
- [ ] Individual note page shows media
|
||||
- [ ] Media lazy loads below fold
|
||||
- [ ] Alt text present for accessibility
|
||||
- [ ] Microformats2 u-photo preserved
|
||||
|
||||
#### Performance Tests
|
||||
- [ ] Page load time acceptable with media
|
||||
- [ ] Images don't block initial render
|
||||
- [ ] Lazy loading works correctly
|
||||
|
||||
### Security Considerations
|
||||
- Media paths already sanitized in media_file route
|
||||
- Alt text must be HTML-escaped in templates
|
||||
- No user-controlled CSS injection points
|
||||
|
||||
### Accessibility Requirements
|
||||
- Alt text MUST be present (fallback to "Image")
|
||||
- Images must not convey information not in text
|
||||
- Focus indicators for keyboard navigation
|
||||
- Proper semantic HTML (figure elements)
|
||||
|
||||
### Future Enhancements (Not for V1)
|
||||
- Image optimization/resizing on upload
|
||||
- WebP format support with fallbacks
|
||||
- Lightbox for full-size viewing
|
||||
- Video/audio media support
|
||||
- CDN integration for media serving
|
||||
|
||||
## Decision Rationale
|
||||
|
||||
### Why Grid Layout?
|
||||
- Native CSS, no JavaScript required
|
||||
- Excellent responsive support
|
||||
- Handles variable image counts elegantly
|
||||
- Familiar social media pattern
|
||||
|
||||
### Why Hide Captions?
|
||||
- Follows Twitter/Mastodon pattern
|
||||
- Captions are for accessibility (alt text)
|
||||
- Cleaner visual presentation
|
||||
- Text content provides context
|
||||
|
||||
### Why Lazy Loading?
|
||||
- Improves initial page load
|
||||
- Reduces bandwidth for visitors
|
||||
- Native browser support
|
||||
- Progressive enhancement
|
||||
|
||||
### Why Aspect Ratio Control?
|
||||
- Prevents layout shift during load
|
||||
- Creates consistent grid appearance
|
||||
- Matches social media expectations
|
||||
- Improves visual harmony
|
||||
|
||||
## Implementation Priority
|
||||
1. **Critical**: Fix homepage media display (functionality gap)
|
||||
2. **High**: Add CSS constraints (UX/visual issue)
|
||||
3. **Medium**: Hide captions (visual polish)
|
||||
|
||||
All three fixes should be implemented together for consistency.
|
||||
153
docs/design/v1.1.2-caption-alttext-update.md
Normal file
153
docs/design/v1.1.2-caption-alttext-update.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# Caption Display Update - Alt Text Only (v1.1.2)
|
||||
|
||||
## Status
|
||||
**Superseded by media-display-fixes.md**
|
||||
|
||||
This document contains an earlier approach to caption handling. The authoritative specification is now in `media-display-fixes.md` which provides a complete solution for media display including caption handling, CSS constraints, and homepage media.
|
||||
|
||||
## Context
|
||||
|
||||
User has clarified that media captions should be used as alt text only, not displayed as visible `<figcaption>` elements in the note body.
|
||||
|
||||
## Decision
|
||||
|
||||
Remove all visible caption display from templates while maintaining caption data for accessibility (alt text) purposes.
|
||||
|
||||
## Required Changes
|
||||
|
||||
### 1. CSS Updates
|
||||
|
||||
**File:** `/home/phil/Projects/starpunk/static/css/style.css`
|
||||
|
||||
**Remove:** Lines related to figcaption styling (line 17 in the media CSS section)
|
||||
|
||||
```css
|
||||
/* REMOVE THIS LINE */
|
||||
.note-media figcaption, .e-content figcaption { margin-top: var(--spacing-sm); font-size: 0.875rem; color: var(--color-text-light); font-style: italic; }
|
||||
```
|
||||
|
||||
The remaining CSS should be:
|
||||
|
||||
```css
|
||||
/* Media Display Styles (v1.2.0) - Updated for alt-text only captions */
|
||||
.note-media { margin-bottom: var(--spacing-md); }
|
||||
.note-media img, .e-content img, .u-photo { max-width: 100%; height: auto; display: block; border-radius: var(--border-radius); }
|
||||
|
||||
/* Multiple media items grid */
|
||||
.note-media { display: flex; flex-wrap: wrap; gap: var(--spacing-md); }
|
||||
.note-media .media-item { flex: 1 1 100%; }
|
||||
|
||||
/* Desktop: side-by-side for multiple images */
|
||||
@media (min-width: 768px) {
|
||||
.note-media .media-item:only-child { flex: 1 1 100%; }
|
||||
.note-media .media-item:not(:only-child) { flex: 1 1 calc(50% - var(--spacing-sm)); }
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Template Updates
|
||||
|
||||
#### File: `/home/phil/Projects/starpunk/templates/note.html`
|
||||
|
||||
**Change:** Lines 17-29 - Simplify media display structure
|
||||
|
||||
**From:**
|
||||
```html
|
||||
{% if note.media %}
|
||||
<div class="note-media">
|
||||
{% for item in note.media %}
|
||||
<figure class="media-item">
|
||||
<img src="{{ url_for('public.media_file', path=item.path) }}"
|
||||
alt="{{ item.caption or 'Image' }}"
|
||||
class="u-photo"
|
||||
width="{{ item.width }}"
|
||||
height="{{ item.height }}">
|
||||
{% if item.caption %}
|
||||
<figcaption>{{ item.caption }}</figcaption>
|
||||
{% endif %}
|
||||
</figure>
|
||||
{% endfor %}
|
||||
</div>
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
**To:**
|
||||
```html
|
||||
{% if note.media %}
|
||||
<div class="note-media">
|
||||
{% for item in note.media %}
|
||||
<div class="media-item">
|
||||
<img src="{{ url_for('public.media_file', path=item.path) }}"
|
||||
alt="{{ item.caption or 'Image' }}"
|
||||
class="u-photo"
|
||||
width="{{ item.width }}"
|
||||
height="{{ item.height }}">
|
||||
</div>
|
||||
{% endfor %}
|
||||
</div>
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
**Changes:**
|
||||
- Replace `<figure>` with `<div>` (simpler, no semantic figure/caption relationship)
|
||||
- Remove the `{% if item.caption %}` block and `<figcaption>` element entirely
|
||||
- Keep caption in `alt` attribute for accessibility
|
||||
|
||||
#### File: `/home/phil/Projects/starpunk/templates/index.html`
|
||||
|
||||
**Status:** No changes needed
|
||||
- Index template doesn't display media items in the preview
|
||||
- Only shows truncated content
|
||||
|
||||
### 3. Feed Generators
|
||||
|
||||
**Status:** No changes needed
|
||||
|
||||
The feed generators already handle captions correctly:
|
||||
- RSS, ATOM, and JSON Feed all use captions as alt text in `<img>` tags
|
||||
- JSON Feed also includes captions in attachment metadata (correct behavior)
|
||||
|
||||
**Current implementation (correct):**
|
||||
```python
|
||||
# In all feed generators
|
||||
caption = media_item.get('caption', '')
|
||||
content_html += f'<img src="{media_url}" alt="{caption}" />'
|
||||
```
|
||||
|
||||
## Rationale
|
||||
|
||||
1. **Simplicity**: Removing visible captions reduces visual clutter
|
||||
2. **Accessibility**: Alt text provides necessary context for screen readers
|
||||
3. **User Intent**: Captions are metadata, not content to be displayed
|
||||
4. **Clean Design**: Images speak for themselves without redundant text
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
- [ ] Update CSS to remove figcaption styles
|
||||
- [ ] Update note.html template to remove figcaption elements
|
||||
- [ ] Test with images that have captions
|
||||
- [ ] Test with images without captions
|
||||
- [ ] Verify alt text is properly set
|
||||
- [ ] Test responsive layout still works
|
||||
- [ ] Verify feed output unchanged
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
1. **Visual Testing:**
|
||||
- Confirm no caption text appears below images
|
||||
- Verify image layout unchanged
|
||||
- Test responsive behavior on mobile/desktop
|
||||
|
||||
2. **Accessibility Testing:**
|
||||
- Inspect HTML to confirm alt attributes are set
|
||||
- Test with screen reader to verify alt text is announced
|
||||
|
||||
3. **Feed Testing:**
|
||||
- Verify RSS/ATOM/JSON feeds still include alt text
|
||||
- Confirm JSON Feed attachments retain title field
|
||||
|
||||
## Standards Compliance
|
||||
|
||||
- **HTML**: Valid use of img alt attribute
|
||||
- **Accessibility**: WCAG 2.1 Level A compliance for images
|
||||
- **IndieWeb**: Maintains u-photo microformat class
|
||||
- **Progressive Enhancement**: Images functional without CSS
|
||||
114
docs/design/v1.2.0-media-css-design.md
Normal file
114
docs/design/v1.2.0-media-css-design.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# CSS Design for Media Display (v1.2.0)
|
||||
|
||||
## Status
|
||||
**Superseded by media-display-fixes.md**
|
||||
|
||||
This document contains an earlier design iteration. The authoritative specification is now in `media-display-fixes.md` which provides a more comprehensive solution including template refactoring and consistent media display across all pages.
|
||||
|
||||
## Problem Statement
|
||||
Images uploaded via the media upload feature display at full resolution, breaking layout bounds and creating poor user experience. Need CSS rules to constrain and style images appropriately.
|
||||
|
||||
## Design Decision
|
||||
|
||||
### CSS Rules to Add
|
||||
|
||||
Add the following CSS rules after line 49 (after `.empty-state` rules) in `/home/phil/Projects/starpunk/static/css/style.css`:
|
||||
|
||||
```css
|
||||
/* Media Display Styles (v1.2.0) */
|
||||
.note-media { margin-bottom: var(--spacing-md); }
|
||||
.note-media figure, .e-content figure { margin: 0 0 var(--spacing-md) 0; }
|
||||
.note-media img, .e-content img, .u-photo { max-width: 100%; height: auto; display: block; border-radius: var(--border-radius); }
|
||||
.note-media figcaption, .e-content figcaption { margin-top: var(--spacing-sm); font-size: 0.875rem; color: var(--color-text-light); font-style: italic; }
|
||||
|
||||
/* Multiple media items grid */
|
||||
.note-media { display: flex; flex-wrap: wrap; gap: var(--spacing-md); }
|
||||
.note-media .media-item { flex: 1 1 100%; }
|
||||
|
||||
/* Desktop: side-by-side for multiple images */
|
||||
@media (min-width: 768px) {
|
||||
.note-media .media-item:only-child { flex: 1 1 100%; }
|
||||
.note-media .media-item:not(:only-child) { flex: 1 1 calc(50% - var(--spacing-sm)); }
|
||||
}
|
||||
```
|
||||
|
||||
## Rationale
|
||||
|
||||
### 1. Responsive Image Constraints
|
||||
- `max-width: 100%` ensures images never exceed container width
|
||||
- `height: auto` maintains aspect ratio
|
||||
- `display: block` removes inline spacing issues
|
||||
- Works with existing HTML `width` and `height` attributes for proper aspect ratio hints
|
||||
|
||||
### 2. Consistent Visual Design
|
||||
- `border-radius: var(--border-radius)` matches existing design system (4px)
|
||||
- Uses existing spacing variables for consistent margins
|
||||
- Caption styling matches `.note-meta` text style (0.875rem, light gray)
|
||||
|
||||
### 3. Flexible Layout
|
||||
- Single images take full width
|
||||
- Multiple images display in a responsive grid
|
||||
- Mobile: stacked vertically (100% width each)
|
||||
- Desktop: two columns for multiple images (50% width each)
|
||||
- Flexbox with gap provides clean spacing
|
||||
|
||||
### 4. Scope Coverage
|
||||
- `.note-media img` - images in the media section
|
||||
- `.e-content img` - images in markdown content
|
||||
- `.u-photo` - microformats photo class (covers both media and author photos)
|
||||
- Applies to both `figure` and standalone `img` elements
|
||||
|
||||
### 5. Performance Considerations
|
||||
- No complex calculations or transforms
|
||||
- Leverages browser native image sizing
|
||||
- Uses existing CSS variables (no new computations)
|
||||
- Respects HTML width/height attributes for layout stability
|
||||
|
||||
## Alternative Approaches Considered
|
||||
|
||||
### Object-fit Approach (Rejected)
|
||||
```css
|
||||
img { object-fit: cover; width: 100%; height: 400px; }
|
||||
```
|
||||
- Rejected: Crops images, losing content
|
||||
- Rejected: Fixed height doesn't work for varied aspect ratios
|
||||
|
||||
### Container Query Approach (Rejected)
|
||||
```css
|
||||
@container (min-width: 600px) { ... }
|
||||
```
|
||||
- Rejected: Limited browser support
|
||||
- Rejected: Unnecessary complexity for this use case
|
||||
|
||||
### CSS Grid Approach (Rejected)
|
||||
```css
|
||||
.note-media { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); }
|
||||
```
|
||||
- Rejected: More complex than needed
|
||||
- Rejected: Less flexible for single vs multiple images
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
1. **Location in style.css**: Insert after line 49, before `.form-group` rules
|
||||
2. **Testing Required**:
|
||||
- Single image display
|
||||
- Multiple images (2, 3, 4 images)
|
||||
- Portrait and landscape orientations
|
||||
- Mobile and desktop viewports
|
||||
- Images in markdown content
|
||||
- Author avatar photos
|
||||
|
||||
3. **Browser Compatibility**: All rules use widely supported CSS features (flexbox, max-width, CSS variables)
|
||||
|
||||
4. **Future Enhancements** (not for v1.2.0):
|
||||
- Lightbox/modal for full-size viewing
|
||||
- Lazy loading optimization
|
||||
- WebP format support
|
||||
- Image galleries with thumbnails
|
||||
|
||||
## Standards Compliance
|
||||
|
||||
- **IndieWeb**: Preserves `.u-photo` microformat class
|
||||
- **Accessibility**: Maintains alt text display, proper figure/figcaption semantics
|
||||
- **Performance**: No JavaScript required, pure CSS solution
|
||||
- **Progressive Enhancement**: Images remain functional without CSS
|
||||
Reference in New Issue
Block a user