A comprehensive educational resource about Ethereum, finance history, and cryptography. Built with Next.js, MDX, and Wikipedia-inspired design principles.
Original Site: inevitableeth.com (Wiki.js) New Site: Modern, performant, Wikipedia-style rebuild
This project is dedicated to Ethereum, the World Computer. It contains 141+ educational articles covering:
- Background: Finance history (1492-2008), mass communication, economic context
- Concepts: Computer science, cryptography, cryptocurrency, finance, mathematics
- Ethereum: Core concepts, consensus, scaling, DeFi, and the future
All content is original, created to help people understand why Ethereum is inevitable.
- Node.js 18+ and npm
- Git
# Clone the repository
git clone https://github.com/rexkirshner/inevitable-eth.git
cd inevitable-eth
# Install dependencies
npm install
# Run the development server
npm run devOpen http://localhost:3000 to view the site.
npm run dev # Start development server with Turbopack
npm run build # Build for production with Turbopack
npm run build:cloudflare # Build for Cloudflare Pages (static export)
npm run start # Start production server
npm run lint # Run ESLint
# Content & Scripts
npm run migrate # Migrate HTML content to MDX (one-time, complete)
npm run check-links # Check for broken internal links
npm run optimize-images # Optimize all images (Sharp + WebP/AVIF)
npm run validate-images # Validate image references and variants
npm run build-search-index # Build optimized search index (auto-runs in prebuild)inevitable-eth/
├── app/ # Next.js App Router pages
├── components/ # React components
│ ├── layout/ # Header, Footer, Sidebar
│ ├── mdx/ # MDX custom components
│ └── ui/ # shadcn/ui components
├── content/ # MDX articles (141 files)
│ ├── background/ # Finance history & context
│ ├── concepts/ # Technical foundations
│ └── ethereum/ # Ethereum-specific content
├── lib/ # Utilities
│ ├── content.ts # Content loading & utilities
│ └── content.schema.ts # Zod validation schemas
├── public/
│ └── images/ # 624+ images
├── scripts/
│ └── migrate-html-to-mdx.ts # Migration script
└── PRD.md # Product Requirements Document
- Framework: Next.js 15.5.4 with App Router
- Styling: Tailwind CSS 4
- Components: shadcn/ui
- Content: MDX with gray-matter
- Validation: Zod
- Search: Fuse.js (client-side)
- Math: rehype-katex
- Theme: next-themes (dark mode)
-
Create a new
.mdxfile in the appropriate category folder:content/background/- Historical and economic contextcontent/concepts/- Technical foundationscontent/ethereum/- Ethereum-specific topics
-
Add frontmatter (see schema in
lib/content.schema.ts):
---
title: "Article Title"
description: "Brief description for SEO and previews"
category: "concepts"
tags: ["tag1", "tag2"]
difficulty: "intermediate"
updated: "2025-10-02"
readingTime: 5
toc: true
related: ["related-article-slug"]
---
# Article Title
Your content here...- The article will automatically appear in navigation and search.
title(required): Article titledescription(required): SEO descriptioncategory(required): "background" | "concepts" | "ethereum"tags(array): Tags for search and filteringdifficulty: "intro" | "intermediate" | "advanced"updated(required): ISO date (YYYY-MM-DD)readingTime: Estimated minutes (auto-calculated if omitted)related(array): Slugs of related articleshero(optional): Path to hero imageinfobox(optional): Key-value pairs for sidebar infoboxtoc(boolean): Show table of contents (default: true)
Create a .env.local file for local development (ignored by git):
# Copy from .env.example
cp .env.example .env.localAdd any API keys or secrets to .env.local (never commit this file).
Wikipedia-inspired information density with modern aesthetics:
- Information-first: Maximize content, minimize chrome
- Typography: Serif body text, sans-serif headings
- Layout: Three-column on desktop (nav, content, TOC)
- Accessibility: Semantic HTML, keyboard navigation, WCAG AA
- Performance: Static generation, optimized images, <2s load times
Recommended: Deploy to Vercel for automatic builds and preview deployments.
# Deploy to production
vercel --prodAlternative: Static export for IPFS or other static hosts.
npm run build
npm run export- Smart Sidebar: Collapsible category tree with article counts and active state tracking
- Table of Contents: Auto-generated with Intersection Observer and smooth scroll
- Breadcrumbs: Wikipedia-style navigation with rich snippet support (BreadcrumbList JSON-LD)
- Prev/Next Navigation: Sequential article browsing
- Related Articles: Tag-based recommendations (3 per article)
- Search: Client-side fuzzy search with Fuse.js
- Random Article: Serendipitous discovery at
/random
- Enhanced Code Blocks: Copy button, language badges, syntax highlighting
- Keyboard Shortcuts: Power user navigation (/, ?, n, p, r, Esc)
- Reading Progress: Scroll-based indicator with smooth animation
- Article Summaries: Info boxes with descriptions
- Font Size Adjuster: 3 sizes with localStorage persistence for accessibility
- Article Bookmarking: Save articles for later with localStorage
- Share Button: Web Share API with copy fallback
- Scroll-to-Top: Appears after scrolling 400px
- Infoboxes: Wikipedia-style sidebar boxes
- Callouts: Warning, info, tip boxes
- Figures: Images with captions
- References: Footnote/citation system
- Mathematical Notation: KaTeX support
- Responsive Images: 6 variants per image (mobile/tablet/desktop × WebP/AVIF)
- Static Generation: All 154 pages pre-rendered at build time
- Image Optimization: Sharp-powered responsive images with blur placeholders
- RSS Feed: All 141 articles with 1-hour ISR caching
- Open Graph: Social media preview images for all pages
- JSON-LD: Structured data for articles and breadcrumbs
- Lighthouse Scores: 93-98 Performance, 96+ Accessibility, 100 SEO
- LCP: 2.6s (90% improvement from 27.3s)
- Dark Mode: Light/dark theme with system preference detection
- Semantic HTML: Proper heading hierarchy, ARIA labels
- Keyboard Navigation: Full keyboard support throughout
- Skip to Content: Accessibility link for screen readers
- Focus Management: Proper focus indicators and tab order
- WCAG AA Compliant: All interactive elements accessible
- TypeScript: Full type safety with Zod runtime validation
- MDX: Flexible content with React component support
- Hot Reload: Turbopack-powered instant updates
- Image Validation: Script to check missing/broken images
- Link Checker: CI-ready broken link detection
- Environment Variables: Configurable GitHub URLs and site settings
- Cloudflare Ready: Static export for Cloudflare Pages
Status: ✅ Production Ready v1 (Phases 1-8 Complete + Session 8 Polish)
Phase 1-8 ✅ Complete
- ✅ Content migration (141 articles, 624+ images)
- ✅ Design system (Wikipedia-inspired, light/dark mode)
- ✅ Layout components (Header, Sidebar, TOC, Footer)
- ✅ MDX components (Infobox, Callout, Figure, References, Code Blocks)
- ✅ Page templates (Home, Category, Article, Search, About, Random, 404, Error)
- ✅ Performance & SEO (Sitemap, Robots, JSON-LD, OG images, CSP headers)
- ✅ QA & Optimization (Link checker, security hardening, Lighthouse 93-98/100)
- ✅ Cloudflare deployment ready
Session 7 (8 Features) ✅ Complete
- Breadcrumbs, Prev/Next navigation, Related articles, Article summaries
- Reading progress, BreadcrumbList JSON-LD, RSS feed, Edit on GitHub links
Session 8 (12 Features) ✅ Complete
- Mobile menu, Enhanced code blocks (copy button), Keyboard shortcuts
- Share button, Font size adjuster, Article bookmarking, Scroll-to-top
- Image validation script, GitHub URLs to env vars, RSS ISR optimization
Current State:
- 154 static pages generated
- 498 images optimized (6 variants each: mobile/tablet/desktop × WebP/AVIF)
- Comprehensive code review: A- overall
- Roadmap brainstormed: 40+ future features
Next: Phase 9+ (Enhanced Discovery, Learning Tools, Community, Content Enhancement) - See roadmap-brainstorm.md
Full Roadmap: See PRD.md for complete product requirements
This is a personal educational project. If you find errors or have suggestions:
- Open an issue
- Submit a pull request
- Reach out directly
All content is original and created by the repository owner. Code is open source.
- Original Site: inevitableeth.com
- Content Backup: github.com/haymsalomon/inevitable-eth
- Next.js: nextjs.org
- MDX: mdxjs.com
Built with ❤️ for the Ethereum community