StarPunk/docs/projectplan/v1.1/syndication-features.md

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

{
  "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
• JSON Feed v1.1
• Microformats2
• IndieWeb h-entry
• IndieWeb h-card