# Syndication Features Specification

## Overview
This document tracks the implementation of expanded syndication format support for StarPunk CMS, targeting v1.1.2 and v1.2.0 releases.

## Feature Set

### 1. ATOM Feed Support (v1.1.2)
**Status**: Planned
**Effort**: 2-4 hours
**Priority**: High

#### Requirements
- RFC 4287 compliance
- Available at `/feed.atom` endpoint
- Include all published notes
- Support same filtering as RSS feed
- Proper content encoding

#### Technical Approach
- Leverage feedgen library's built-in ATOM support
- Minimal code changes from RSS implementation
- Share note iteration logic with RSS feed

#### Acceptance Criteria
- [ ] Valid ATOM 1.0 feed generated
- [ ] Passes W3C Feed Validator
- [ ] Contains all RSS feed content
- [ ] Auto-discovery link in HTML head
- [ ] Content properly escaped/encoded
- [ ] Unit tests with 100% coverage

### 2. JSON Feed Support (v1.1.2)
**Status**: Planned
**Effort**: 4-6 hours
**Priority**: Medium

#### Requirements
- JSON Feed v1.1 specification compliance
- Available at `/feed.json` endpoint
- Native JSON serialization
- Support attachments for future media

#### Technical Approach
- Direct serialization from Note model
- No XML parsing/generation
- Clean JSON structure
- Optional fields for extensibility

#### JSON Feed Structure
```json
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Site Name",
  "home_page_url": "https://example.com",
  "feed_url": "https://example.com/feed.json",
  "description": "Site description",
  "items": [
    {
      "id": "unique-id",
      "url": "https://example.com/note/slug",
      "content_html": "<p>HTML content</p>",
      "date_published": "2025-11-25T10:00:00Z",
      "date_modified": "2025-11-25T10:00:00Z"
    }
  ]
}
```

#### Acceptance Criteria
- [ ] Valid JSON Feed v1.1 output
- [ ] Passes JSON Feed Validator
- [ ] Proper HTML encoding in content_html
- [ ] ISO 8601 date formatting
- [ ] Auto-discovery link in HTML head
- [ ] Unit tests with full coverage

### 3. Strict Microformats2 Support (v1.2.0)
**Status**: Planned
**Effort**: 10-16 hours
**Priority**: High (IndieWeb core requirement)

#### Requirements
- Complete h-entry markup
- Author h-card implementation
- h-feed on index pages
- Backward compatible with existing CSS

#### Implementation Scope

##### h-entry (Enhanced)
Current state:
- ✅ h-entry class
- ✅ e-content
- ✅ dt-published
- ✅ u-url

To add:
- [ ] p-name (extracted title)
- [ ] p-summary (excerpt generation)
- [ ] p-author (embedded h-card)
- [ ] p-category (when tags implemented)
- [ ] u-uid (unique identifier)

##### h-card (New)
- [ ] p-name (author name from config)
- [ ] u-url (author URL from config)
- [ ] u-photo (optional avatar)
- [ ] p-note (optional bio)

##### h-feed (New)
- [ ] h-feed wrapper on index
- [ ] p-name (site title)
- [ ] p-author (site-level h-card)
- [ ] Nested h-entry items

#### Template Changes Required
1. `base.html` - Add author h-card in header/footer
2. `index.html` - Wrap notes in h-feed
3. `note.html` - Complete h-entry properties
4. New partial: `note_summary.html` for consistent markup

#### Acceptance Criteria
- [ ] Passes microformats2 validator
- [ ] Parseable by IndieWeb tools
- [ ] XRay parser compatibility
- [ ] CSS remains functional
- [ ] No visual regression
- [ ] Documentation of all mf2 classes used

## Testing Strategy

### Feed Validation
1. W3C Feed Validator for ATOM
2. JSON Feed Validator for JSON
3. Microformats2 parser for HTML

### Automated Tests
- Unit tests for feed generation
- Integration tests for endpoints
- Validation tests using external validators
- Regression tests for existing RSS

### Manual Testing
- Multiple feed readers compatibility
- IndieWeb tools parsing
- Social readers integration

## Dependencies

### External Libraries
- feedgen (existing) - ATOM support included
- No new dependencies for JSON Feed
- No new dependencies for microformats2

### Configuration
- New config options for author info (h-card)
- Feed URLs in auto-discovery links

## Migration Impact
- None - all features are additive
- Existing RSS feed unchanged
- No database changes required

## Documentation Requirements
1. Update user guide with feed URLs
2. Document microformats2 markup
3. Add feed discovery information
4. Include validation instructions

## Risk Assessment

### Low Risk
- ATOM feed (uses existing library)
- JSON Feed (simple serialization)

### Medium Risk
- Microformats2 (template complexity)
- CSS selector conflicts

### Mitigation
- Incremental template changes
- Thorough CSS testing
- Use mf2 validators throughout

## Success Metrics
- All feeds validate successfully
- No performance degradation
- Feed readers consume without errors
- IndieWeb tools parse correctly
- Zero visual regression in UI

## References
- [RFC 4287 - ATOM](https://www.rfc-editor.org/rfc/rfc4287)
- [JSON Feed v1.1](https://www.jsonfeed.org/version/1.1/)
- [Microformats2](https://microformats.org/wiki/microformats2)
- [IndieWeb h-entry](https://indieweb.org/h-entry)
- [IndieWeb h-card](https://indieweb.org/h-card)