Files
StarPunk/docs/decisions/ADR-040-microformats2-compliance.md
T
PhilandClaude Opus 5.5 978c13358b feat: article titles and summaries stored apart from the text (v2.16.0, ADR-076)
Articles as the IndieWeb defines them: a name separate from the content.

- Migration 023 adds notes.title and notes.summary. A one-time Python data
  step (migrations.DATA_MIGRATIONS) moves each note's '# Heading' first line
  into title, rewrites the file and hash, empties FTS for a rebuild, and puts
  files back if the migration fails. Trashed notes included.
- Micropub: name -> title, summary stored when sent with content, summary
  updatable, q=source returns both. MCP tools take a summary.
- Feeds: titles only for articles (RSS/JSON none, Atom empty); Atom and
  JSON Feed summaries; the title is no longer repeated in the content.
- Pages: p-name/p-summary on the article page. Homepage and tag pages show
  articles as title, summary and "Read more" without images (hidden u-photo
  keeps the post type for parsers).
- Crossposts: articles go out as title, summary, link and hashtags, no
  images; the Bluesky card is the article. Notes unchanged.
- Editor: Title and Summary fields; an article may have no body.
- Fix: a line starting with a hashtag ('#indieweb ...') was rendered as a
  heading and crossposted without its '#' (HashtagLineExtension).
- Fix: excerpts showed raw Markdown; they are plain text now.

Back up the database and the data folder before deploying: the migration
rewrites note files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 17:05:38 -07:00

2.5 KiB

ADR-023: Strict Microformats2 Compliance

Status

Accepted (implemented in v1.3.0, reviewed in v2.8.0; was: Proposed)

Since v2.16.0 p-name is the stored title and p-summary the author's summary or, in previews, the start of the text (ADR-076).

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

  1. Core IndieWeb Requirement: Microformats2 is fundamental to IndieWeb data exchange
  2. Template-Only Changes: No backend modifications required
  3. Progressive Enhancement: Adds semantic value without breaking existing functionality
  4. Standards Maturity: Microformats2 spec is stable and well-documented
  5. 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

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

Implementation Scope

Required Markup

  1. h-entry (complete):

    • p-name (title extraction)
    • p-summary (excerpt)
    • p-category (when tags added)
    • p-author with embedded h-card
  2. h-card (author):

    • p-name (author name)
    • u-url (author URL)
    • u-photo (avatar, optional)
  3. 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