feat(templates): Add microformats2 h-feed and p-category markup for tags

Implement Phase 2 of v1.3.0 per microformats-tags-design.md

Template Updates:
- templates/index.html: Add h-feed properties (u-url, enhanced p-author with u-photo/p-note, feed-level u-photo)
- templates/index.html: Add p-category markup with rel="tag" to note previews
- templates/note.html: Add p-category markup with rel="tag" for tags
- templates/note.html: Enhance author h-card with u-photo and p-note (hidden for parsers)
- templates/note.html: Document u-photo placement outside e-content per draft spec
- templates/tag.html: Create new tag archive template with h-feed structure

Key Decisions Applied:
- Tags ordered alphabetically by display_name (ready for backend)
- rel="tag" on all p-category links per microformats2 spec
- Author bio (p-note) hidden with display: none for semantic parsing
- Dual u-photo elements intentional for parser compatibility
- Graceful fallback when author photo/bio not available

Templates are backward compatible and ready for backend integration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2025-12-10 11:35:11 -07:00
parent f10d0679da
commit 377027e79a
4 changed files with 251 additions and 5 deletions

View File

@@ -0,0 +1,138 @@
# v1.3.0 Phase 2: Templates Implementation Report
**Date**: 2025-12-10
**Developer**: StarPunk Developer Agent
**Phase**: Phase 2 - Templates
**Status**: Complete
## Summary
Successfully implemented Phase 2 of the v1.3.0 Microformats2 Compliance and Tags feature. All template updates have been completed according to the design specification in `microformats-tags-design.md`.
## Changes Implemented
### 1. Updated `templates/index.html`
Added h-feed required properties per microformats2 specification:
- **u-url**: Added self-referencing feed URL (hidden with `display: none`)
- **Enhanced p-author h-card**:
- Added `u-photo` when author.photo is available
- Added `p-note` (bio) when author.note is available
- Maintained hidden state for semantic parsing
- **Feed-level u-photo**: Added duplicate u-photo for broad parser compatibility (intentional per architect decision)
- **p-category markup**: Added tag links with `rel="tag"` attribute on note previews
- Uses `tag.name` for URL (normalized)
- Displays `tag.display_name` (preserves case)
### 2. Updated `templates/note.html`
Enhanced individual note pages with:
- **u-photo placement documentation**: Added comment explaining that u-photo must be direct child of h-entry (not inside e-content) per draft spec
- **p-category markup**: Added tags section in footer with:
- `p-category` class on each tag link
- `rel="tag"` attribute per microformats2 specification
- Links to `/tag/<normalized_name>` route
- **Enhanced author h-card**:
- Reordered: photo first, then name/url
- Added `p-note` (bio) with `display: none` for semantic-only parsing
- Graceful fallback when photo or bio not available
### 3. Created `templates/tag.html`
New template for tag archive pages:
- Extends `base.html` and imports `display_media` macro
- Uses h-feed structure with p-name showing tag display name
- Shows all notes with the tag (no pagination for v1.3.0)
- Reuses same note preview structure as index.html for consistency:
- Conditional p-name for explicit titles
- Media previews
- Truncated e-content (300 chars)
- Full note metadata including tags, timestamp, author
- Empty state message when no notes found
- Back navigation link to homepage
## Key Design Decisions Applied
All architect Q&A decisions were correctly implemented:
1. **Tag ordering**: Alphabetically by display_name (case-insensitive) - ready for backend
2. **rel="tag" attribute**: Added to all p-category links per specification
3. **Author bio visibility**: Hidden with `display: none` - semantic only for parsers
4. **Dual u-photo elements**: Maintained intentionally for parser compatibility
5. **u-photo placement**: Verified and documented as correct (outside e-content)
## Files Changed
### Modified Files
- `/home/phil/Projects/starpunk/templates/index.html`
- `/home/phil/Projects/starpunk/templates/note.html`
### New Files
- `/home/phil/Projects/starpunk/templates/tag.html`
## Verification
### Template Structure Checks
All templates follow the architect's microformats2 specifications:
- h-feed on index and tag pages with required properties (p-name, u-url, p-author, u-photo)
- h-entry on note previews and individual pages with required properties (e-content, dt-published, u-url)
- p-category markup with rel="tag" on all tag links
- Enhanced h-card with u-photo and p-note where available
- Graceful fallback for missing author properties
### Code Quality
- Clean, readable Jinja2 syntax
- Consistent with existing template patterns
- Comprehensive comments explaining microformats decisions
- No hardcoded values - all URLs use `url_for()`
- Proper conditional rendering for optional fields
## Dependencies for Next Phase
Templates are ready and will work once backend implementation is complete:
- **Phase 1 backend**: Must implement `tags` module and update `notes.py` to populate `note.tags`
- **Phase 3 routes**: Tag links will 404 until `/tag/<tag>` route is implemented
- **Context processor**: Author data already injected via existing context processor
## Testing Notes
Templates can be manually inspected but full testing requires:
1. Backend implementation to populate `note.tags` property
2. Tag route implementation for tag archive pages
3. Author discovery system (already exists) providing photo and bio data
## Standards Compliance
All changes follow:
- Microformats2 h-feed specification
- Microformats2 h-entry specification
- Microformats2 h-card specification
- Microformats2 p-category specification with rel="tag"
- Project coding standards for templates
- Existing template patterns and structure
## Issues Encountered
None. All template updates completed successfully according to specification.
## Next Steps
Ready for Phase 3 implementation:
1. Add tag archive route to `starpunk/routes/public.py`
2. Update admin forms for tag editing
3. Load tags in public routes (index, note)
## Notes
- The test failure in `test_migration_race_condition.py` is a pre-existing flaky test unrelated to template changes
- Templates are backward compatible - work fine when `note.tags` is empty or None
- No CSS changes required per architect decision (out of scope)