Blog v2.0 Navigation Enhancements — Implementation Brief

For Socrates 🧠 | 2026-04-22

Approved Features (Priority Order)

P1: Related Posts (Highest Impact)

Location: Bottom of article, above footer

Logic:
- Match by primary category first
- Fallback to any shared category
- Exclude current post
- Max 3 posts
- Sort by published date (newest first)

API needed:

GET /api/blog/posts/{slug}/related?limit=3
Response: [{slug, title, excerpt, category, published_at}]

UI:

RELATED FROM HOME LAB
─────────────────────

The Night I Accidentally DDoSed Myself
A tale of infinite loops and ISP angry emails
[Read →]

How Tailscale Saved My Marriage (and My Sanity)
Remote access without the VPN headache
[Read →]

Why I Ditched Cloudflare for Caddy
Simpler, faster, fewer surprises
[Read →]

P2: Category Header Pills

Location: Below site header, above hero/content

Current: Text links (Home Lab, OpenClaw, AI News, etc.)

New: Pill buttons, active state highlight

HoffDesk                      [Search] [RSS]

[All] [Home Lab] [OpenClaw] [AI News] [Tech] [Life]
       ────────── (active pill, underlined)

Behavior:
- Click pill → filter to that category
- Active pill: solid background, no border
- Inactive: ghost style
- URL: /?category=homelab

Mobile: Horizontal scroll, snap to active

P3: Cmd+K Search (Delight)

Trigger: Cmd+K (Mac) / Ctrl+K (Windows)

UI:

┌─────────────────────────────────────────┐
│  🔍  Search posts...                    │
├─────────────────────────────────────────┤
│                                         │
│  The Night I Broke DNS         Home Lab │
│  How I Migrated to CalDAV      OpenClaw │
│  ...                                    │
│                                         │
│            47 results      [↵ to open]  │
└─────────────────────────────────────────┘

Implementation:
- Modal overlay (not new page)
- Debounced search (300ms)
- Arrow key navigation
- Enter to open
- Esc to close
- Focus trap

API:

GET /api/blog/search?q={query}&limit=10
Response: [{slug, title, category, excerpt_highlight}]

Frontend:
- Fuse.js for local cache (if posts < 100)
- Or fetch on type if backend search

P4: Reading Progress Indicator

Location: Fixed to top of viewport (0px)

Visual:
- Thin line (3px height)
- Accent color (--color-primary)
- Width: 0% → 100% based on scroll
- Smooth animation (no jank)

Implementation:

window.addEventListener('scroll', () => {
  const scroll = window.scrollY;
  const height = document.body.scrollHeight - window.innerHeight;
  const progress = (scroll / height) * 100;
  document.getElementById('reading-progress').style.width = progress + '%';
});

Mobile: Same, stays visible during scroll

P5: Next/Previous Links (Lowest Priority)

Location: Bottom of article, below related posts

Logic:
- Chronological order (not category)
- Previous: older post
- Next: newer post

UI:

[← Previous: Why I Switched to Local LLMs]
                              [Next: The Great DNS Outage →]

Mobile: Stack vertically

API:

GET /api/blog/posts/{slug}/adjacent
Response: {
  previous: {slug, title} | null,
  next: {slug, title} | null
}

API Summary for Socrates

Notes:
- All endpoints return published posts only
- Exclude posts with status != published
- Cache aggressively (5 min TTL)

Frontend Deliverables (Daedalus)

Explicitly NOT Included

• ❌ Social sharing buttons
• ❌ Newsletter signup
• ❌ Comment sections
• ❌ Like/bookmark buttons

Responsive Breakpoints

Accessibility

• Search: Cmd+K announced to screen readers
• Progress: aria-hidden (decorative)
• Related: aria-label="Related posts"
• Navigation: Focus visible on pills

Priority for implementation:
1. Category Pills (can do now)
2. Related Posts (needs API)
3. Cmd+K Search (needs API or Fuse.js)
4. Progress Bar (pure frontend)
5. Prev/Next (needs API)

Which should Socrates build first?