IF.docs.md2html/PROJECT_SUMMARY.md

# IF.docs.md2html - Project Summary

## What We Built

A **magazine-style Markdown viewer** that transforms plain `.md` files into beautiful, animated documents using the **ICW NextSpread design system** from icantwait.ca property showcase.

## Key Features

### 🎨 Design System (Ported from ICW)
- **Typography**: Inter headings, system fonts for body, JetBrains Mono for code
- **Colors**: Neutral palette (50-900), Primary green (#10B981)
- **Spacing**: 8-point grid system, generous white space
- **Animations**: Webflow-style ease curves `[0.25, 0.46, 0.45, 0.94]`

### ✨ Animations (ICW Property Page Patterns)
- **Adaptive Duration**: Animation speed adjusts to scroll velocity
  - Fast scroll = shorter animations (0.5x speed)
  - Slow scroll = longer animations (1.5x speed)
- **Staggered Reveals**: Gallery-style cascade with 50ms delays
- **Scroll Triggers**: IntersectionObserver with -10% margin
- **Reduced Motion**: Respects accessibility preferences

### 📱 Layout
- **Magazine Grid**: 2-column main content + 1-column sidebar (desktop)
- **Full-Bleed Hero**: 40vh mobile, 50vh desktop with gradient overlay
- **Sticky Sidebar**: Navigation panel follows scroll
- **Responsive**: Mobile-first (320px) → Desktop (1440px+)

### 🚀 Functionality
- **Drag-and-Drop Upload**: `.md` and `.markdown` files
- **URL Parsing**: `?parse=https://url/file.md` query parameter
- **Syntax Highlighting**: VS Code Dark+ theme via highlight.js
- **Static Export**: Pre-rendered HTML for fast loading

## Components

### HeroSection (`src/components/HeroSection.tsx`)
- Full-bleed hero with gradient overlay
- Animated badge, title, CTA buttons
- ICW-style drop shadows and backdrop blur

### MagazineContent (`src/components/MagazineContent.tsx`)
- 2-column grid layout
- Staggered element reveals via IntersectionObserver
- Sticky sidebar with navigation

### MarkdownViewer (`src/components/MarkdownViewer.tsx`)
- Main wrapper component
- Orchestrates hero + content sections
- Adaptive animation timing

### FileUploader (`src/components/FileUploader.tsx`)
- Drag-and-drop zone with hover states
- File input fallback
- Loading spinner and error states

## Animation Hooks

### useAdaptiveDuration (`src/lib/useAdaptiveDuration.ts`)
```typescript
// Adjusts animation speed based on scroll velocity
const duration = useAdaptiveDuration(0.6); // Base 0.6s
// Returns: 0.3s (fast scroll) → 0.9s (slow scroll)
```

### useScrollSpeed (`src/lib/useScrollSpeed.ts`)
```typescript
// Measures scroll velocity (0-100 scale)
const scrollSpeed = useScrollSpeed();
// 0 = stationary, 100 = max speed (5000px/s)
```

### useClientReady (`src/lib/useClientReady.ts`)
```typescript
// Prevents hydration mismatches
const isReady = useClientReady();
if (!isReady) return <Skeleton />;
```

## Styling

### Markdown Prose (`src/styles/markdown.css`)
- **Headings**: -0.02em letter spacing, tracking-tight
- **Drop Cap**: First paragraph first letter (6xl, float left)
- **Lead Paragraph**: First paragraph 2xl size
- **Links**: Underline on hover with smooth transition
- **Blockquotes**: Magazine pull-quote style with left border
- **Code Blocks**: Rounded corners, VS Code theme
- **Images**: Full-width with rounded corners and shadows

### Syntax Highlighting (`src/styles/highlight.css`)
- VS Code Dark+ theme colors
- Background: `#1e1e1e`
- Keywords: `#569cd6` (blue)
- Strings: `#ce9178` (orange)
- Comments: `#6a9955` (green)

## Deployment Configuration

### Next.js Config (`next.config.mjs`)
```javascript
{
  output: 'export',                           // Static export
  basePath: '/infrafabric/IF.docs.md2html',  // StackCP path
  images: { unoptimized: true }              // No image optimization
}
```

### Apache Config (`.htaccess`)
- SPA routing (all requests → index.html)
- CORS headers for external markdown fetching
- Gzip compression for text files
- Browser caching (1 hour HTML, 1 month CSS/JS)

## Usage Examples

### Local Development
```bash
npm install
npm run dev
# Open http://localhost:3000
```

### File Upload
1. Drag `.md` file onto dropzone
2. Or click "Choose File" button
3. Document renders with magazine layout + animations

### URL Parsing
```
http://localhost:3000?parse=https://raw.githubusercontent.com/user/repo/main/README.md
```

### Production (StackCP)
```
https://digital-lab.ca/infrafabric/IF.docs.md2html
https://digital-lab.ca/infrafabric/IF.docs.md2html?parse=https://example.com/docs.md
```

## File Structure

```
IF.docs.md2html/
├── src/
│   ├── app/
│   │   ├── layout.tsx              # Root layout
│   │   └── page.tsx                # Home page (Suspense wrapper)
│   ├── components/
│   │   ├── FileUploader.tsx        # Drag-and-drop UI
│   │   ├── HeroSection.tsx         # ICW-style hero
│   │   ├── MagazineContent.tsx     # Magazine layout
│   │   ├── MarkdownViewer.tsx      # Main viewer
│   │   └── ViewerContent.tsx       # URL param handler
│   ├── lib/
│   │   ├── markdown-parser.ts      # markdown-it config
│   │   ├── useAdaptiveDuration.ts  # Animation hook
│   │   ├── useScrollSpeed.ts       # Scroll tracker
│   │   └── useClientReady.ts       # Hydration guard
│   └── styles/
│       ├── globals.css             # Base + Tailwind
│       ├── markdown.css            # Prose styling
│       └── highlight.css           # Code theme
├── out/                            # Build output
├── .htaccess                       # Apache config
├── DEPLOY.md                       # Deployment guide
├── README.md                       # User documentation
└── PROJECT_SUMMARY.md              # This file
```

## Technical Highlights

### Performance
- **Static Export**: Pre-rendered HTML, no server required
- **Code Splitting**: Automatic via Next.js
- **Lazy Loading**: Images below fold
- **Gzip Compression**: ~70% size reduction
- **First Load**: 477 kB (main page)

### Accessibility
- **Reduced Motion**: Respects `prefers-reduced-motion`
- **Keyboard Navigation**: Tab order, focus indicators
- **Semantic HTML**: Proper heading hierarchy
- **Touch Targets**: 44px+ minimum size

### Browser Support
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Mobile browsers (iOS 14+, Android Chrome 90+)

## Design Credits

**Ported from ICW NextSpread** (icantwait.ca):
- Property page animations (HeroEditorial, Gallery, About components)
- Adaptive duration timing system
- Scroll-speed-based animation adjustments
- Webflow-style easing curves
- Typography scale and color palette
- Touch target sizes and spacing

**Inspired by**:
- Airbnb editorial pages (magazine layouts)
- Medium long-form articles (typography)
- Notion docs (clean, readable prose)

## Repository

- **GitHub**: https://github.com/dannystocker/IF.docs.md2html
- **Branch**: `main`
- **Commit**: f950357

## Next Steps

1. **Deploy to StackCP**: Follow `DEPLOY.md` instructions
2. **Test URL parsing**: Try with InfraFabric docs
3. **Add features**:
   - Table of contents sidebar
   - Dark mode toggle
   - Export to PDF
   - Social sharing
   - Print stylesheet

## License

MIT

---

**Created**: 2025-11-14
**Author**: Claude Code
**Design System**: ICW NextSpread (icantwait.ca)