dannystocker/IF.docs.md2html
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
IF.docs.md2html/PROJECT_SUMMARY.md
Danny Stocker db191beaec docs: Add comprehensive project summary
2025-11-14 17:52:53 +01:00

7.2 KiB
Raw Export PDF Permalink Blame History

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)

// 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)

// Measures scroll velocity (0-100 scale)
const scrollSpeed = useScrollSpeed();
// 0 = stationary, 100 = max speed (5000px/s)

useClientReady (src/lib/useClientReady.ts)

// 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)

{
  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

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

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)