# 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:**
```javascript
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

| Endpoint | Priority | Purpose |
|----------|----------|---------|
| `GET /api/blog/posts/{slug}/related` | P1 | Related posts by category |
| `GET /api/blog/search` | P3 | Full-text search |
| `GET /api/blog/posts/{slug}/adjacent` | P5 | Prev/next navigation |

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

---

## Frontend Deliverables (Daedalus)

| Component | File | Notes |
|-----------|------|-------|
| Category Pills | `blog_index.html.j2` | Replace current nav |
| Search Modal | `components/search_modal.html.j2` | Include in base |
| Progress Bar | `base.html.j2` | Fixed position |
| Related Posts | `blog_article.html.j2` | Below content |
| Prev/Next | `blog_article.html.j2` | Footer of article |

---

## Explicitly NOT Included

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

---

## Responsive Breakpoints

| Feature | Desktop | Tablet | Mobile |
|---------|---------|--------|--------|
| Category Pills | Inline | Inline | Horizontal scroll |
| Search | Modal | Modal | Fullscreen |
| Progress Bar | 3px fixed | 3px fixed | 3px fixed |
| Related | 3-col grid | 2-col grid | Stack |
| Prev/Next | Side by side | Side by side | Stack |

---

## 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?**