Neumann's Workshop

A modern React-based digital studio and workshop where Jared Neumann shares projects, writings, and insights on AI, development, language, and philosophy. Built with Next.js and deployed as a static site to GitHub Pages.

🏗️ Architecture

This site is built with Next.js 14 and React 18, featuring:

• Static Site Generation (SSG) for optimal performance and SEO
• TypeScript for type safety and better development experience
• Victorian Scholar Aesthetic with refined monochrome design
• Mobile-First Responsive Design with comprehensive breakpoints
• Interactive Timeline with filtering and search capabilities
• Individual Post Pages with rich SEO metadata and social previews

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Open http://localhost:3000

Building & Deployment

# Build for production
npm run build

# Export static files
npm run export

# Files will be in ./out/ directory

📁 Project Structure

src/
├── app/                    # Next.js App Router
│   ├── layout.tsx         # Root layout with metadata
│   ├── page.tsx           # Homepage
│   ├── posts/[slug]/      # Dynamic post pages
│   ├── sitemap.ts         # Automated sitemap generation
│   └── robots.ts          # SEO robots configuration
├── components/
│   ├── content/           # Content-specific components
│   │   ├── FeaturedSection.tsx    # Latest project updates
│   │   └── TimelineSection.tsx    # Interactive timeline
│   ├── layout/            # Layout components
│   │   ├── Sidebar.tsx            # Bio and navigation
│   │   └── WorkshopStatus.tsx     # Current status system
│   └── shared/            # Reusable components
├── lib/
│   ├── projectLoader.ts   # Project and event discovery
│   ├── markdown.ts        # Markdown processing
│   └── utils.ts           # Utility functions
└── types/
    └── index.ts           # TypeScript interfaces

public/
├── projects/              # Project content and metadata (empty)
└── assets/               # Images and static files

📝 Content Management

Project Structure

Each project follows this structure:

public/projects/{project-name}/
├── project.yaml          # Project metadata
├── events/              # Chronological updates
│   └── YYYY-MM-DD-title.md
└── images/              # Project screenshots

Adding New Content

1. Create Event File: Add a new Markdown file in the appropriate project's events/ directory:

   ---
   title: "Your Update Title"
   date: "2025-01-13"
   description: "Brief description for previews"
   author: "human" # or "ai" or "collaborative"
   image: "../images/screenshot.png" # optional
   ---
   
   Your content here...

2. Update Project Metadata: Ensure project.yaml has current information:

   name: "Project Name"
   description: "Project description"
   status: "active" # or "beta", "completed", etc.

3. Commit and Push: Changes are automatically deployed via GitHub Actions

Supported Frontmatter

• title: Post title (required)
• date: Publication date in YYYY-MM-DD format (required)
• description: Brief summary for previews and SEO (required)
• author: "human", "ai", or "collaborative" (affects byline display)
• image: Relative path to post image (optional)

🎨 Design System

Victorian Scholar Aesthetic

• Primary Colors: Sophisticated charcoal (#5A5A5A) and warm whites
• Typography: Elegant serif fonts with proper hierarchy
• Interactions: Subtle hover effects and smooth transitions
• Mobile: Touch-friendly 44px minimum targets

Key Components

• Workshop Status: Cycling status display with elegant gradients
• Timeline: Interactive filtering by project with search functionality
• Featured Carousel: Latest updates from each active project
• Byline System: Elegant authorship attribution

🔧 Technical Features

SEO & Social Media

• Individual pages for each post with unique URLs
• Open Graph metadata for rich social media previews
• Project-specific social media images
• Automated sitemap and robots.txt generation
• Dynamic RSS Feed at /feed.xml with all project timeline events

RSS Feed

• Automatic Generation: RSS feed dynamically generated from all project events
• Complete Coverage: Ready for timeline events when projects are added
• Proper URLs: Links to individual post pages (/posts/project-date-title/)
• RSS 2.0 Compliant: Proper XML structure with escaping and metadata
• Author Attribution: Each item includes authorship information for filtering
• Cached: 1-hour cache for optimal performance
• Subscribe: https://neumanns-workshop.github.io/feed.xml

RSS Author Filtering

The RSS feed includes detailed author attribution that allows readers to filter content by authorship type:

• Human-authored: by Jared - Content written primarily by Jared
• AI-generated: by AI - Content generated primarily by AI systems
• Collaborative: by Jared & AI - Content created through human-AI collaboration

Most RSS readers and feed aggregators support filtering by author, enabling subscribers to:

• Follow only human-authored strategic updates
• Track AI-generated technical documentation
• Monitor collaborative research and development posts
• Get complete timeline coverage across all authorship types

Performance

• Static site generation for fast loading
• Optimized images and assets
• Minimal JavaScript bundle with code splitting

Accessibility

• Semantic HTML structure
• Proper ARIA labels and roles
• Keyboard navigation support
• Mobile-responsive design

🚢 Deployment

The site automatically deploys to GitHub Pages via GitHub Actions when changes are pushed to the main branch.

Workflow:

1. Push to main branch
2. GitHub Actions runs npm run build && npm run export
3. Static files deployed to gh-pages branch
4. Site live at https://neumanns-workshop.github.io

📊 Analytics

Analytics integration is configured but requires environment variables for production deployment.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes following the existing patterns
4. Test locally with npm run dev
5. Submit a pull request

📄 License

© 2025 Neumann's Workshop, LLC. All rights reserved.

📧 Contact

• Email: jared@neumannsworkshop.com
• LinkedIn: Jared Neumann
• GitHub: neumanns-workshop