From db191beaec4e1c71ab13960d10b2dbda8cdf5174 Mon Sep 17 00:00:00 2001 From: Danny Stocker Date: Fri, 14 Nov 2025 17:52:53 +0100 Subject: [PATCH] docs: Add comprehensive project summary --- PROJECT_SUMMARY.md | 231 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 PROJECT_SUMMARY.md diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md new file mode 100644 index 0000000..1c4158b --- /dev/null +++ b/PROJECT_SUMMARY.md @@ -0,0 +1,231 @@ +# 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 ; +``` + +## 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)