Files

Phil Skentelbery e589f5bd6c docs: Fix ADR numbering conflicts and create comprehensive documentation indices

This commit resolves all documentation issues identified in the comprehensive review:

CRITICAL FIXES:
- Renumbered duplicate ADRs to eliminate conflicts:
  * ADR-022-migration-race-condition-fix → ADR-037
  * ADR-022-syndication-formats → ADR-038
  * ADR-023-microformats2-compliance → ADR-040
  * ADR-027-versioning-strategy-for-authorization-removal → ADR-042
  * ADR-030-CORRECTED-indieauth-endpoint-discovery → ADR-043
  * ADR-031-endpoint-discovery-implementation → ADR-044

- Updated all cross-references to renumbered ADRs in:
  * docs/projectplan/ROADMAP.md
  * docs/reports/v1.0.0-rc.5-migration-race-condition-implementation.md
  * docs/reports/2025-11-24-endpoint-discovery-analysis.md
  * docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md
  * docs/decisions/ADR-044-endpoint-discovery-implementation.md

- Updated README.md version from 1.0.0 to 1.1.0
- Tracked ADR-021-indieauth-provider-strategy.md in git

DOCUMENTATION IMPROVEMENTS:
- Created comprehensive INDEX.md files for all docs/ subdirectories:
  * docs/architecture/INDEX.md (28 documents indexed)
  * docs/decisions/INDEX.md (55 ADRs indexed with topical grouping)
  * docs/design/INDEX.md (phase plans and feature designs)
  * docs/standards/INDEX.md (9 standards with compliance checklist)
  * docs/reports/INDEX.md (57 implementation reports)
  * docs/deployment/INDEX.md (deployment guides)
  * docs/examples/INDEX.md (code samples and usage patterns)
  * docs/migration/INDEX.md (version migration guides)
  * docs/releases/INDEX.md (release documentation)
  * docs/reviews/INDEX.md (architectural reviews)
  * docs/security/INDEX.md (security documentation)

- Updated CLAUDE.md with complete folder descriptions including:
  * docs/migration/
  * docs/releases/
  * docs/security/

VERIFICATION:
- All ADR numbers now sequential and unique (50 total ADRs)
- No duplicate ADR numbers remain
- All cross-references updated and verified
- Documentation structure consistent and well-organized

These changes improve documentation discoverability, maintainability, and
ensure proper version tracking. All index files follow consistent format
with clear navigation guidance.

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

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-25 13:28:56 -07:00

2.3 KiB

Raw Blame History

ADR-023: Strict Microformats2 Compliance

Status

Proposed

Context

StarPunk currently implements basic microformats2 markup:

h-entry on note articles
e-content for note content
dt-published for timestamps
u-url for permalinks

"Strict" microformats2 compliance would add comprehensive markup for full IndieWeb interoperability, enabling better parsing by readers, Webmention receivers, and IndieWeb tools.

Decision

Enhance existing templates with complete microformats2 vocabulary, focusing on h-entry, h-card, and h-feed structures.

Rationale

Core IndieWeb Requirement: Microformats2 is fundamental to IndieWeb data exchange
Template-Only Changes: No backend modifications required
Progressive Enhancement: Adds semantic value without breaking existing functionality
Standards Maturity: Microformats2 spec is stable and well-documented
Testing Tools Available: Validators exist for compliance verification

Consequences

Positive

Full IndieWeb parser compatibility
Better social reader integration
Improved SEO through semantic markup
Enables future Webmention support (v1.3.0)

Negative

More complex HTML templates
Careful CSS selector management needed
Testing requires microformats2 parser

Alternatives Considered

Minimal Compliance: Current state - rejected as incomplete for IndieWeb tools
Microdata/RDFa: Not IndieWeb standard, adds complexity
JSON-LD: Additional complexity, not IndieWeb native

Implementation Scope

Required Markup

h-entry (complete):
- p-name (title extraction)
- p-summary (excerpt)
- p-category (when tags added)
- p-author with embedded h-card
h-card (author):
- p-name (author name)
- u-url (author URL)
- u-photo (avatar, optional)
h-feed (index pages):
- p-name (feed title)
- p-author (feed author)
- Nested h-entry items

Template Updates Required

/templates/base.html - Add h-card in header
/templates/index.html - Add h-feed wrapper
/templates/note.html - Complete h-entry properties
/templates/partials/note_summary.html - Create for consistent h-entry

Effort Estimate

Template Analysis: 2-3 hours
Markup Implementation: 4-6 hours
CSS Compatibility Check: 1-2 hours
Testing with mf2 parser: 2-3 hours
Documentation: 1-2 hours
Total: 10-16 hours

2.3 KiB Raw Blame History