Skip to content

project-spec.md

Latest commit

 

History

History
547 lines (426 loc) · 15 KB

project-spec.md

File metadata and controls

547 lines (426 loc) · 15 KB
Raw

JustinMitchel.com Modernization - Technical Specification

Project Overview

Modernize justinmitchel.com into a cutting-edge blog platform that builds personal brand through exceptional user experience while maintaining markdown-based authoring simplicity.

Core Philosophy: Approachable expert - technically excellent but inviting, fast but feature-rich, distinctive but not gimmicky.

Tech Stack

Framework & Hosting

  • Framework: Astro (island architecture for progressive enhancement)
  • Hosting: Cloudflare Pages
  • Rendering Strategy: Static site generation + Cloudflare Workers for dynamic enhancements
  • Content Source: Markdown files in GitHub repository
  • Deployment: Auto-deploy on every commit to main branch

Key Technologies

  • Styling: TBD (likely Tailwind or vanilla CSS with design tokens)
  • Analytics: Cloudflare Web Analytics
  • Newsletter: ConvertKit integration
  • Search: Client-side full-text search (Fuse.js or Pagefind)
  • Asset Storage: Co-located in GitHub repo with markdown files

Performance Requirements

Primary Goal: Sub-100ms First Contentful Paint

Strategy: Performance-first progressive enhancement

  1. Static HTML and critical CSS load instantly (target: <100ms FCP)
  2. Core content readable immediately with zero JavaScript
  3. Enhanced features (personalization, animations, search) load after core content
  4. Return visitors benefit from cached assets and preferences

Key Optimizations:

  • Inline critical CSS
  • Defer all non-critical JavaScript
  • Optimize font loading (FOFT or system font fallback)
  • Aggressive image optimization
  • Minimal bundle size for initial load
  • Progressive enhancement for all interactive features

Core Features

1. Personalized Content Discovery: "Algo for Them"

Concept: Dual-feed system with personalized recommendations alongside chronological timeline.

User Flow:

  1. New visitor reads 1-2 posts (standard chronological view)
  2. Subtle prompt appears: "Get personalized content recommendations?"
  3. If accepted: Show 3-5 topic/interest questions
  4. Save preferences to localStorage
  5. Display personalized feed alongside "All Posts" timeline

Technical Implementation:

  • Content Tagging: Semantic extraction at build time

    • Use AI/NLP to extract topics, keywords, themes from post content
    • Store in frontmatter or separate index
    • No manual tagging required (though can override in frontmatter)

  • Matching Algorithm:

    • Client-side matching of user preferences to post topics
    • Weight by topic relevance, recency, engagement
    • Progressive enhancement - works without JS (falls back to chronological)

  • Preference Storage:

    • localStorage for persistence
    • No account required
    • Export/import capability for power users

UI Components:

  • Topic selection modal (appears after scroll/time threshold)
  • Toggle between "For You" and "All Posts" views
  • Preference management page
  • Reset/reconfigure option

2. SEO & Metadata

Priority: Critical - organic search is primary growth channel

Implementation:

  • Auto-generated Metadata:

    • AI-generated SEO meta descriptions at build time
    • Review and override capability in frontmatter
    • Compelling, click-worthy descriptions

  • OpenGraph & Social:

    • Rich OpenGraph cards with custom images
    • Twitter/X Card optimization (large image summary)
    • Auto-generate social images or use custom per post
    • Proper meta tags for LinkedIn, Facebook, etc.

  • Technical SEO:

    • XML sitemap (auto-generated)
    • Structured data (JSON-LD for BlogPosting)
    • Semantic HTML5
    • Proper heading hierarchy
    • Fast Core Web Vitals scores

  • RSS Feed:

    • Full-content RSS/Atom feed
    • Proper formatting for feed readers
    • Auto-updated on new posts

3. Code Display & Developer Features

Requirements:

  • Syntax highlighting for all major languages
  • Copy button on all code blocks
  • Track copy events in analytics (engagement signal)
  • File context when relevant (filename, language indicator)
  • Line numbers for reference
  • Diff highlighting support for code comparisons

Technical Details:

  • Use Shiki or Prism for syntax highlighting
  • Copy button as progressive enhancement
  • Track copy events to Cloudflare Analytics as custom events
  • Highlight specific lines via frontmatter config

4. Interactive Elements (Progressive Enhancement)

All animations and interactions load AFTER core content to maintain sub-100ms FCP target.

Features:

  1. Smooth Page Transitions

    • View transitions API where supported
    • Shared element morphing between pages
    • Loading states that feel instant
    • Fallback to instant navigation on unsupported browsers

  2. Interactive Reading Progress

    • Visual progress indicator (top bar or circular)
    • Estimated reading time
    • Smart back-to-top button (appears on scroll)
    • Section navigation for long posts
    • Preview content on hover over links

  3. Animated Graph/Timeline Visualization

    • Visual representation of content relationships
    • Topic clusters with connecting lines
    • Temporal timeline view option
    • Interactive exploration of post connections
    • "Related posts" as interactive graph

  4. Subtle Micro-interactions

    • Hover states on cards and buttons
    • Scroll-triggered reveals (fade in, slide up)
    • Smooth focus states for accessibility
    • Loading animations (skeleton screens)
    • Haptic feedback on mobile where supported

Technical Implementation:

  • Use Astro islands for interactive components
  • GSAP or Framer Motion for complex animations
  • CSS animations for simple transitions
  • RequestAnimationFrame for performance
  • Respect prefers-reduced-motion

5. Search Functionality

Type: Simple client-side full-text search

Implementation:

  • Use Pagefind or Fuse.js
  • Index all post content at build time
  • Fast fuzzy search
  • Search titles, content, and extracted topics
  • Keyboard shortcuts (Cmd+K or Ctrl+K)
  • Instant results as you type

UI:

  • Modal overlay (like Algolia DocSearch)
  • Keyboard navigable results
  • Preview snippets with highlights
  • Direct navigation to results

6. Dark Mode

Strategy: System preference default with manual override

Implementation:

  • Detect system preference on load
  • Manual toggle persists to localStorage
  • Smooth transition between modes
  • Consistent color scheme across both modes
  • High contrast in both modes for readability

Color Palette:

  • Technical blue/cyan as primary accent
  • Clean monochrome base (black/white/grays)
  • Monospace font accents in headings or code
  • WCAG AA minimum contrast ratios

7. Typography

Direction: Clean technical with monospace accents

Font Stack:

  • Body: Modern sans-serif (Inter, System UI stack)
  • Headings: Monospace accents (JetBrains Mono, Fira Code, or similar)
  • Code: Monospace (Cascadia Code, JetBrains Mono)
  • Fallbacks: System font stack for performance

Typography Scale:

  • Fluid typography (responsive to viewport)
  • Optimal line length (60-80 characters)
  • Generous line height for readability (1.6-1.8)
  • Proper hierarchy (clear heading sizes)

8. Analytics & Metrics

Service: Cloudflare Web Analytics (privacy-focused, zero performance impact)

Custom Events to Track:

  • Code snippet copy events (which snippets are most useful)
  • Reading depth (how far users scroll)
  • Time on page (engagement measurement)
  • Personalization opt-in rate
  • "For You" vs "All Posts" usage
  • Popular topics and trending posts
  • Traffic sources and attribution
  • Search queries (what users look for)

Privacy:

  • No personal data collection
  • No cookies required
  • GDPR-compliant by default
  • Transparent about tracking

9. Newsletter Integration

Service: ConvertKit

Features:

  • Email capture form (non-intrusive placement)
  • Inline CTAs in posts
  • Landing page for newsletter
  • Auto-sync new posts to subscribers
  • Tag subscribers by interests (based on which posts they sign up from)

UX Considerations:

  • Not too pushy - subtle CTAs
  • Clear value proposition
  • Easy unsubscribe
  • Privacy-focused (no spam, no sharing)

10. Social & Engagement

Comments: None - drive discussion to social media

Rationale:

  • Avoid moderation burden
  • Centralize discussion where audience already is (Twitter, LinkedIn)
  • Link to social threads from posts
  • Encourage thoughtful replies vs quick comments

Social Sharing:

  • Share buttons for Twitter, LinkedIn, Reddit
  • Pre-filled share text (title + URL)
  • Track shares in analytics (if possible)
  • OpenGraph preview optimization

Content Architecture

Repository Structure

Flat structure with frontmatter metadata:

/posts/
  post-one.md
  post-two.md
  another-post.md
/images/ (or /assets/)
  post-one/
    image.jpg
  post-two/
    diagram.png

Frontmatter Schema:

---
title: "Post Title"
date: 2024-01-15
draft: false # Set to true to hide from production
description: "Optional custom meta description" # AI-generated if omitted
tags: ["optional", "manual", "tags"] # Semantic extraction supplements these
ogImage: "/images/custom-og.jpg" # Optional custom social image
---

Content Migration

Requirement: Migrate all existing content from current site

Approach:

  1. Audit existing posts
  2. Convert to consistent frontmatter format
  3. Update any relative links/image paths
  4. Ensure all assets are included
  5. Set up redirects for any URL changes
  6. Verify no broken links
  7. Maintain SEO juice (301 redirects if needed)

Build-time Processing:

  1. Parse markdown + frontmatter
  2. Run semantic extraction (topics, keywords)
  3. Generate AI meta descriptions (if not provided)
  4. Optimize images
  5. Generate static pages
  6. Create search index
  7. Generate RSS feed
  8. Generate sitemap

Mobile & Responsive Design

Strategy: Responsive - works well on all screen sizes

Breakpoints:

  • Mobile: 320px - 640px
  • Tablet: 641px - 1024px
  • Desktop: 1025px+

Mobile-Specific Considerations:

  • Touch-friendly targets (44px minimum)
  • Readable font sizes (16px minimum)
  • Simplified navigation on small screens
  • Optimized images for mobile bandwidth
  • Fast interaction response
  • Respect mobile data (lazy load images)

Progressive Web App Features (Optional):

  • Service worker for offline reading
  • Install prompt for frequent visitors
  • Cached content for return visits

Deployment & Build

Build Pipeline

Trigger: Auto-deploy on push to main branch

Build Steps:

  1. Clone repo from GitHub
  2. Install dependencies
  3. Run semantic extraction on all posts
  4. Generate AI meta descriptions
  5. Build Astro site (static generation)
  6. Optimize assets
  7. Generate search index
  8. Deploy to Cloudflare Pages

Build Performance:

  • Incremental builds where possible
  • Cache dependencies
  • Parallel processing of posts
  • Target: <2 minute build time

Draft Workflow

Strategy: Commit to main = instant publish with draft protection

Implementation:

  • Set draft: true in frontmatter for WIP posts
  • Drafts excluded from production builds
  • No preview branches needed
  • Simple and fast iteration

Optional Enhancement:

  • Add /drafts route in dev mode to preview
  • Query param to preview drafts in production (with auth)

Technical Implementation Details

Astro Configuration

Islands Architecture:

  • Static HTML by default
  • Client-side hydration only for interactive components
  • Directive usage:
    • client:load for critical interactions (search, nav)
    • client:visible for below-fold content (animations)
    • client:idle for non-critical features (analytics)

Key Pages:

  • Homepage (with dual feed: For You / All Posts)
  • Post detail page
  • Topic/tag pages
  • About/Now page
  • Newsletter landing page
  • Search results

Cloudflare Integration

Cloudflare Pages:

  • Static asset hosting
  • Global CDN
  • Auto SSL
  • Preview deployments for branches (if needed)

Cloudflare Workers (Edge Functions):

  • Serverless functions for dynamic features
  • Could be used for:
    • Real-time view counts (optional)
    • Server-side search (if client-side too slow)
    • A/B testing (if needed)
    • Rate limiting

Cloudflare Analytics:

  • Web Analytics beacon
  • Custom events via JavaScript
  • Dashboard for metrics

Other Cloudflare Services (Optional):

  • R2 for large media (if needed later)
  • KV for edge data storage (feature flags, configs)
  • D1 for structured data (if outgrow static approach)

Semantic Extraction Implementation

Build-time Processing:

  • Use AI model (GPT-4, Claude, or local model) during build
  • Extract: topics, keywords, categories, related concepts
  • Store in frontmatter or separate index file
  • Use for personalization matching
  • Use for "related posts" suggestions

Example Output:

{
  "postId": "my-post-slug",
  "extractedTopics": ["React", "Performance", "Web Vitals"],
  "primaryCategory": "Web Development",
  "relatedPosts": ["other-post-slug"],
  "difficulty": "intermediate",
  "estimatedReadTime": 8
}

Personalization Matching Algorithm

Client-side JavaScript:

// Simplified example
function matchPosts(userPreferences, allPosts) {
  return allPosts.map(post => ({
    ...post,
    score: calculateRelevance(post.topics, userPreferences)
  }))
  .sort((a, b) => b.score - a.score)
  .filter(post => post.score > THRESHOLD)
}

Weighting Factors:

  • Topic match strength (primary weight)
  • Recency (decay over time)
  • Engagement (popular posts weighted slightly higher)
  • Diversity (avoid showing only one topic)

Success Metrics

Performance Targets

  • First Contentful Paint: <100ms
  • Largest Contentful Paint: <1s
  • Time to Interactive: <2s
  • Cumulative Layout Shift: <0.1
  • Lighthouse Score: 95+ across all categories

Engagement Targets

  • Average session duration: >3 minutes
  • Pages per session: >2
  • Return visitor rate: >30%
  • Personalization opt-in rate: >40%
  • Newsletter conversion: >5%

SEO Targets

  • Organic search traffic: Primary growth channel
  • Domain authority improvement
  • Featured snippets for key topics
  • High ranking for branded searches

Future Enhancements (Out of Scope for V1)

  • Multi-language support
  • Video content integration
  • Interactive demos/sandboxes
  • Course landing pages
  • Member-only content
  • Web monetization
  • Real-time collaboration features
  • Commenting system (if social approach doesn't work)

Open Questions & Decisions

Resolved: All critical questions answered through interview process.

Ready for Implementation: Yes - specification is complete and actionable.

Next Steps

  1. Set up Astro project structure
  2. Configure Cloudflare Pages deployment
  3. Implement base theme (typography, colors, dark mode)
  4. Build core layouts (homepage, post, list)
  5. Implement semantic extraction pipeline
  6. Build personalization UI and logic
  7. Migrate existing content
  8. Implement search
  9. Add analytics and tracking
  10. ConvertKit integration
  11. Polish animations and interactions
  12. Performance optimization
  13. SEO audit and optimization
  14. Launch!

Document Version: 1.0 Last Updated: 2025-12-30 Status: Complete - Ready for Development