astro-website/openspec/changes/blog-umami-fix/design.md

Context

The site uses Umami for analytics. Most site clickables are instrumented using Umami’s data-attribute method (data-umami-event and optional data-umami-event-* properties) so events are recorded automatically on click.

The Blog section was added recently and its clickables (post cards, category nav, page links) are not consistently emitting Umami events. This creates a measurement blind spot for the /blog surface.

Goals / Non-Goals

Goals:

• Ensure all blog clickables emit Umami events using the documented data-attribute method.
• Ensure every tracked clickable has a deterministic, unique target_id and includes at minimum placement and target_url per taxonomy.
• Keep event names within Umami limits (<= 50 chars) and avoid sending event data without an event name.
• Add tests to prevent regressions (blog pages/components should contain required Umami attributes).

Non-Goals:

• Introducing custom JavaScript tracking (window.umami.track) for v1; we will use Umami’s data-attribute method.
• Adding new analytics providers or changing Umami initialization.
• Tracking PII or user-generated content in event properties.

Decisions

• Decision: Use Umami-native data attributes on every blog clickable.

  • Rationale: Aligns with Umami’s “Track events” docs and the rest of the site’s tracking approach; avoids adding JS listeners that can interfere with other handlers.

• Decision: Use consistent event names by clickable type.

  • Rationale: Keeps reporting clean while still allowing segmentation via event properties.
  • Proposed:
    • click for internal navigation links (including blog category navigation)
    • outbound_click for external links (if any in blog chrome)

• Decision: Add a deterministic target_id namespace for blog elements.

  • Rationale: Blog has many repeated elements; we need unique IDs that remain stable across builds.
  • Proposed conventions:
    • Blog header link: nav.blog
    • Blog secondary nav: blog.subnav.all, blog.subnav.pages, blog.subnav.category.<slug>
    • Blog post card: blog.card.post.<slug> (placement blog.index or blog.category.<slug>)
    • Blog post detail back link: blog.post.back
    • Blog page list links: blog.pages.link.<slug>

Risks / Trade-offs

• [Risk] Some blog content areas render raw HTML from WordPress; links inside content are not instrumented. -> Mitigation: Track the blog chrome (cards/nav/back links) first; consider JS-based delegated tracking for content-body links in a future change if needed.
• [Risk] Over-instrumentation adds noisy events. -> Mitigation: Keep event names simple, rely on target_id + placement for segmentation, and avoid tracking non-clickable elements.