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>
198 lines
5.0 KiB
Markdown
198 lines
5.0 KiB
Markdown
# 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) |