Phil Skentelbery
f10d0679da
Implements tag/category system backend following microformats2 p-category specification. Database changes: - Migration 008: Add tags and note_tags tables - Normalized tag storage (case-insensitive lookup, display name preserved) - Indexes for performance New module: - starpunk/tags.py: Tag management functions - normalize_tag: Normalize tag strings - get_or_create_tag: Get or create tag records - add_tags_to_note: Associate tags with notes (replaces existing) - get_note_tags: Retrieve note tags (alphabetically ordered) - get_tag_by_name: Lookup tag by normalized name - get_notes_by_tag: Get all notes with specific tag - parse_tag_input: Parse comma-separated tag input Model updates: - Note.tags property (lazy-loaded, prefer pre-loading in routes) - Note.to_dict() add include_tags parameter CRUD updates: - create_note() accepts tags parameter - update_note() accepts tags parameter (None = no change, [] = remove all) Micropub integration: - Pass tags to create_note() (tags already extracted by extract_tags()) - Return tags in q=source response Per design doc: docs/design/v1.3.0/microformats-tags-design.md Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
5.0 KiB
5.0 KiB
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.atomendpoint - 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.jsonendpoint - 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
base.html- Add author h-card in header/footerindex.html- Wrap notes in h-feednote.html- Complete h-entry properties- New partial:
note_summary.htmlfor 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
- W3C Feed Validator for ATOM
- JSON Feed Validator for JSON
- 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
- Update user guide with feed URLs
- Document microformats2 markup
- Add feed discovery information
- 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