Brandon Lucas
7e76acab18
Website rebuilt from scratch based on analysis of 11 beloved language websites (Elm, Zig, Gleam, Swift, Kotlin, Haskell, OCaml, Crystal, Roc, Rust, Go). New website structure: - Homepage with hero, playground, three pillars, install guide - Language Tour with interactive lessons (hello world, types, effects) - Examples cookbook with categorized sidebar - API documentation index - Installation guide (Nix and source) - Sleek/noble design (black/gold, serif typography) Also includes: - New stdlib/json.lux module for JSON serialization - Enhanced stdlib/http.lux with middleware and routing - New string functions (charAt, indexOf, lastIndexOf, repeat) - LSP improvements (rename, signature help, formatting) - Package manager transitive dependency resolution - Updated documentation for effects and stdlib - New showcase example (task_manager.lux) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
36 KiB
36 KiB
Lux Website: Complete Learning Funnel
A comprehensive plan for a world-class language website, based on deep analysis of 11 beloved programming language websites.
Research Summary
Languages Analyzed
| Language | Standout Feature | Primary Learning Tool | Hero Tagline |
|---|---|---|---|
| Elm | Friendly errors, semantic versioning | Playground + Guide | "Delightful language for reliable web apps" |
| Zig | C interop, comptime, transparent governance | Examples + version-specific docs | "Robust, optimal, reusable software" |
| Gleam | Lucy mascot, friendly tone, values-driven | Language Tour (editable, compiles in browser) | "Friendly, type-safe, scales" |
| Swift | Use-case pathways, multiplatform focus | Domain-organized docs | "Powerful, flexible, multiplatform" |
| Kotlin | Koans exercises, enterprise adoption | Playground + Koans + case studies | "Concise. Multiplatform. Fun." |
| Haskell | Academic rigor, expandable features | Playground + progressive disclosure | "Long-term maintainable software" |
| OCaml | Industry adoption, curated resources | Play + searchable API + exercises | "Industrial-strength functional" |
| Crystal | Ruby-like syntax, production stories | Try Online + 8 progressive examples | "For humans and computers" |
| Roc | Effects notation, clickable annotations | Browser REPL with inline explanations | "Fast, friendly, functional" |
| Rust | The Book (legendary) | Book + Rustlings exercises + enhanced quizzes | "Reliable, efficient, productive" |
| Go | Tour of Go (gold standard) | Interactive tour with exercises | "Build simple, secure, scalable" |
Common Navigation Patterns
Elm: Install | Packages | Guide | News
Zig: Download | Learn | News | Source | Community | ZSF | Devlog
Gleam: News | Community | Sponsor | Packages | Docs | Code
Swift: Documentation | Community | Packages | Blog | Install
Kotlin: Solutions | Docs | API | Community | Teach
OCaml: Learn | Tools | Packages | Community | News | Play
Crystal: Blog | Install | Sponsors | Community | Docs
Roc: Tutorial | Install | Examples | Community | Docs | Donate
Synthesized Navigation for Lux:
[Logo] Install | Tour | Examples | Docs | Play | Community
Learning Funnel Pattern
All successful language sites follow this progression:
┌─────────────────────────────────────────────────────────────────┐
│ 1. HERO │
│ 3-5 word memorable tagline + immediate code example │
│ Value props as 3 pillars │
│ CTAs: "Try Now" + "Install" + "Learn More" │
├─────────────────────────────────────────────────────────────────┤
│ 2. TRY NOW (Zero Friction) │
│ Browser-based playground │
│ No account, no install, no setup │
│ Editable code with immediate feedback │
├─────────────────────────────────────────────────────────────────┤
│ 3. WHY THIS LANGUAGE │
│ 3-4 key differentiators with code examples │
│ Problem/solution framing │
│ Social proof (testimonials, adoption) │
├─────────────────────────────────────────────────────────────────┤
│ 4. INSTALL │
│ One-liner with copy button │
│ Multiple platform options │
│ Verification steps │
├─────────────────────────────────────────────────────────────────┤
│ 5. INTERACTIVE TOUR │
│ Step-by-step lessons (10-20) │
│ Editable code that compiles in browser │
│ Progressive complexity │
│ Single-page version available │
├─────────────────────────────────────────────────────────────────┤
│ 6. BY EXAMPLE │
│ Cookbook of common patterns │
│ Categorized (basics, web, cli, data, concurrent) │
│ Copy-paste ready │
├─────────────────────────────────────────────────────────────────┤
│ 7. DEEP DIVES │
│ Unique features explained thoroughly │
│ Effects system, behavioral types │
│ For Lux: what makes it different │
├─────────────────────────────────────────────────────────────────┤
│ 8. REAL PROJECTS │
│ 3-5 complete applications │
│ Full source, tests, README │
│ Demonstrates real-world usage │
├─────────────────────────────────────────────────────────────────┤
│ 9. API REFERENCE │
│ Searchable │
│ Every function documented │
│ Type signatures prominent │
├─────────────────────────────────────────────────────────────────┤
│ 10. LANGUAGE SPEC │
│ Formal grammar (EBNF) │
│ Operator precedence │
│ Reserved words │
│ Complete specification │
└─────────────────────────────────────────────────────────────────┘
Interactive Elements (Best Practices)
| Site | Feature | Implementation |
|---|---|---|
| Gleam Tour | Editable code compiles on every keystroke | WASM in browser |
| Kotlin Koans | Exercises with immediate feedback | Server-side execution |
| Go Tour | Step-by-step with navigation | Client+server hybrid |
| Roc | Clickable code annotations | JS tooltips |
| Haskell | Expandable feature sections | CSS/JS accordion |
| TypeScript | Live error highlighting | Monaco editor |
Effective Tutorial Structure (from Go Tour, Gleam Tour)
Lesson Structure:
1. Concept introduction (2-3 sentences)
2. Editable code example
3. Output panel
4. Key points to notice (2-3 bullets)
5. Navigation (← Previous | Next →)
6. Contents dropdown
Go Tour Topics (reference):
- Packages, imports, exported names
- Functions (multiple returns, named returns)
- Variables (declaration, initialization, short syntax)
- Basic types (bool, string, int, float, complex)
- Zero values
- Type conversions
- Constants
- For loops (the only loop)
- If statements
- Switch
- Defer
- Pointers
- Structs
- Arrays and Slices
- Maps
- Function values and closures
- Methods
- Interfaces
- Errors
- Goroutines
- Channels
- Select
- Mutexes
- Exercises throughout
Gleam Tour Topics (reference):
- Hello World
- Type inference
- Custom types
- Pattern matching
- Pipelines
- Result type
- Concurrency
- Interop
Lux Website Architecture
Site Map
lux-lang.org/
│
├── / # Homepage (hero, playground, value props)
│
├── /install # Installation guide (multi-platform)
│
├── /tour/ # Interactive Language Tour
│ ├── 01-hello-world
│ ├── 02-values-types
│ ├── 03-functions
│ ├── 04-custom-types
│ ├── 05-pattern-matching
│ ├── 06-effects-intro
│ ├── 07-using-effects
│ ├── 08-custom-handlers
│ ├── 09-testing-effects
│ ├── 10-modules
│ ├── 11-behavioral-types
│ ├── 12-compilation
│ └── all # Single-page version
│
├── /examples/ # By Example cookbook
│ ├── basics/
│ │ ├── hello-world
│ │ ├── values
│ │ ├── variables
│ │ ├── functions
│ │ ├── closures
│ │ ├── recursion
│ │ └── ...
│ ├── types/
│ │ ├── records
│ │ ├── variants
│ │ ├── generics
│ │ ├── option
│ │ └── result
│ ├── effects/
│ │ ├── console-io
│ │ ├── file-operations
│ │ ├── http-requests
│ │ ├── random-numbers
│ │ ├── time-sleep
│ │ ├── state-management
│ │ └── error-handling
│ ├── data/
│ │ ├── json-parsing
│ │ ├── json-generation
│ │ ├── string-processing
│ │ ├── list-operations
│ │ ├── sqlite-database
│ │ └── postgresql
│ ├── concurrent/
│ │ ├── spawning-tasks
│ │ ├── channels
│ │ ├── producer-consumer
│ │ └── parallel-map
│ └── web/
│ ├── http-server
│ ├── rest-api
│ ├── middleware
│ └── routing
│
├── /learn/ # Deep-dive guides
│ ├── effects # Complete effects system guide
│ ├── behavioral-types # Pure, total, idempotent, commutative
│ ├── compilation # How Lux compiles to C
│ ├── performance # Optimization guide
│ └── from-x/ # Coming from other languages
│ ├── rust
│ ├── haskell
│ ├── typescript
│ └── python
│
├── /projects/ # Complete example applications
│ ├── todo-api # REST API with persistence
│ ├── cli-tool # Full CLI application
│ ├── web-scraper # HTTP + JSON processing
│ └── concurrent-worker # Task queue with channels
│
├── /docs/ # API Reference
│ ├── stdlib/
│ │ ├── list
│ │ ├── string
│ │ ├── option
│ │ ├── result
│ │ ├── math
│ │ └── json
│ ├── effects/
│ │ ├── console
│ │ ├── file
│ │ ├── process
│ │ ├── http
│ │ ├── http-server
│ │ ├── time
│ │ ├── random
│ │ ├── state
│ │ ├── fail
│ │ ├── sql
│ │ ├── postgres
│ │ ├── concurrent
│ │ ├── channel
│ │ └── test
│ └── spec/
│ ├── grammar # EBNF grammar
│ ├── operators # Precedence table
│ └── keywords # Reserved words
│
├── /play # Full-page playground
│
├── /community # Community resources
│ ├── discord
│ ├── contributing
│ └── code-of-conduct
│
└── /blog # Technical posts and news
Page Specifications
1. Homepage (/)
Hero Section:
┌─────────────────────────────────────────────────────────────────────┐
│ │
│ Side Effects Can't Hide │
│ │
│ See what your code does. Test without mocks. Ship with confidence.│
│ │
│ [Try Now] [Install] [Take the Tour] │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ fn processOrder(order: Order): Receipt with {Database, Email} │ │
│ │ // The signature tells you EVERYTHING │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ MIT Licensed · 372+ Tests · Native Performance │
│ │
└─────────────────────────────────────────────────────────────────────┘
Problem/Solution Section: Side-by-side comparison:
- Left: "Other Languages" - hidden side effects
- Right: "Lux" - explicit effect signatures
Three Pillars Section:
-
Effects You Can See
- Type signatures reveal all side effects
- Code example showing
with {Console, Http}
-
Testing Without Mocks
- Swap handlers, not implementations
- Code example: production vs test handlers
-
Native Performance
- Compiles to C via gcc/clang
- Benchmark comparison (Lux vs Rust vs Go vs Node)
Embedded Playground: 5 tabs with runnable examples:
- Hello World
- Effects Basics
- Pattern Matching
- Custom Handlers
- Behavioral Types
Getting Started:
# One command (Nix)
nix run git+https://git.qrty.ink/blu/lux
# From source
git clone https://git.qrty.ink/blu/lux && cd lux && cargo build --release
Footer: Source · Docs · Community · Blog
2. Language Tour (/tour/)
Design (inspired by Go Tour + Gleam Tour):
┌─────────────────────────────────────────────────────────────────────┐
│ Tour of Lux [Contents ▾] [1 of 12] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ # Hello World │
│ │
│ Every Lux program starts with a `main` function. Functions that │
│ perform side effects declare them with `with {...}`. │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ fn main(): Unit with {Console} = { │ │
│ │ Console.print("Hello, Lux!") │ │
│ │ } │ │
│ │ │ │
│ │ run main() with {} │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ [Run ▶] │
│ │
│ Output: │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Hello, Lux! │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ **Key points:** │
│ • `with {Console}` declares this function uses console I/O │
│ • `run ... with {}` executes the effectful code │
│ • The type `Unit` means the function returns nothing │
│ │
│ │
│ [← Previous] [Next: Values & Types →] │
└─────────────────────────────────────────────────────────────────────┘
Lessons:
| # | Title | Topics |
|---|---|---|
| 1 | Hello World | main function, Console effect, run syntax |
| 2 | Values & Types | Int, Float, String, Bool, type annotations |
| 3 | Functions | Function syntax, anonymous functions, higher-order |
| 4 | Custom Types | Type aliases, records, algebraic data types |
| 5 | Pattern Matching | match expressions, destructuring, exhaustiveness |
| 6 | Effects: The Basics | What are effects, using built-in effects |
| 7 | Using Multiple Effects | Effect composition, propagation |
| 8 | Custom Handlers | handler syntax, resume(), handler substitution |
| 9 | Testing with Effects | Mock handlers, testing without mocks |
| 10 | Modules | Module structure, imports, visibility |
| 11 | Behavioral Types | is pure, is total, is idempotent, is commutative |
| 12 | Compilation | How Lux compiles to C, native performance |
Interactive Features:
- Editable code (textarea with syntax highlighting)
- Run button (server-side execution or WASM)
- Output panel (shows stdout, stderr, errors)
- Contents dropdown for jumping to any lesson
- Progress indicator (1 of 12)
- Single-page version at
/tour/all
3. Examples (/examples/)
Structure (inspired by Go by Example, Rust by Example):
┌─────────────────────────────────────────────────────────────────────┐
│ Lux by Example │
├───────────────────────┬─────────────────────────────────────────────┤
│ │ │
│ BASICS │ # HTTP Server │
│ Hello World │ │
│ Values │ Lux provides `HttpServer` for building │
│ Variables │ web services with explicit effect tracking. │
│ Functions │ │
│ Closures │ ```lux │
│ Recursion │ fn main(): Unit with {HttpServer, Console} │
│ │ = { │
│ TYPES │ HttpServer.listen(8080) │
│ Records │ Console.print("Listening on :8080") │
│ Variants │ │
│ Generics │ loop { │
│ Option │ let req = HttpServer.accept() │
│ Result │ match req.path { │
│ │ "/" => HttpServer.respond( │
│ EFFECTS │ 200, "Hello!"), │
│ Console I/O ◄ │ _ => HttpServer.respond( │
│ File Operations │ 404, "Not Found") │
│ HTTP Requests │ } │
│ Random Numbers │ } │
│ Time/Sleep │ } │
│ State │ ``` │
│ Error Handling │ │
│ │ The effect signature `{HttpServer, Console}`│
│ DATA │ tells you exactly what this server does. │
│ JSON Parsing │ │
│ JSON Generation │ **Try it:** │
│ String Processing │ ```bash │
│ List Operations │ lux run server.lux │
│ SQLite │ curl http://localhost:8080/ │
│ PostgreSQL │ ``` │
│ │ │
│ CONCURRENT │ │
│ Spawning Tasks │ [← File Operations] [HTTP Requests →] │
│ Channels │ │
│ Producer/Consumer │ │
│ │ │
│ WEB │ │
│ HTTP Server │ │
│ REST API │ │
│ Middleware │ │
│ Routing │ │
│ │ │
└───────────────────────┴─────────────────────────────────────────────┘
4. Deep-Dive Guides (/learn/)
Effects Guide (/learn/effects)
- What are algebraic effects?
- Comparison: effects vs monads vs async/await
- Built-in effects reference
- Custom effect definition
- Handler patterns (logging, mocking, state)
- Effect composition
- Best practices
Behavioral Types Guide (/learn/behavioral-types)
- What are behavioral types?
is pure- function has no effectsis total- function always terminatesis deterministic- same inputs → same outputsis idempotent- safe to call multiple timesis commutative- argument order doesn't matter- Compiler verification
- Optimization benefits
- Real-world use cases
Compilation Guide (/learn/compilation)
- How Lux compiles to C
- Memory management (reference counting + FBIP)
- Performance characteristics
- Interfacing with C libraries
- Build options and flags
Coming From X (/learn/from-x/)
/learn/from-x/rust- For Rust developers/learn/from-x/haskell- For Haskell developers/learn/from-x/typescript- For TypeScript developers/learn/from-x/python- For Python developers
Each compares Lux concepts to familiar patterns.
5. Projects (/projects/)
Complete, runnable example applications:
Todo API (/projects/todo-api)
todo-api/
├── src/
│ ├── main.lux # Entry point
│ ├── routes.lux # HTTP routes
│ ├── handlers.lux # Request handlers
│ ├── models.lux # Data types
│ └── db.lux # Database operations
├── tests/
│ └── handlers_test.lux # Tests with mock handlers
└── README.md # Full documentation
Features demonstrated:
- REST API design
- SQLite persistence
- JSON serialization
- Effect-based testing
CLI Tool (/projects/cli-tool)
- Argument parsing
- File processing
- Progress output
- Error handling
Web Scraper (/projects/web-scraper)
- HTTP requests
- JSON parsing
- Concurrent fetching
- Data extraction
6. API Reference (/docs/)
Format:
┌─────────────────────────────────────────────────────────────────────┐
│ Docs > Stdlib > List [Search 🔍] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ # List │
│ │
│ Operations on immutable lists. │
│ │
│ ## Functions │
│ │
│ ### map │
│ │
│ ```lux │
│ fn map<A, B>(list: List<A>, f: fn(A): B): List<B> │
│ ``` │
│ │
│ Applies `f` to each element, returning a new list. │
│ │
│ **Example:** │
│ ```lux │
│ List.map([1, 2, 3], fn(x: Int): Int => x * 2) │
│ // Result: [2, 4, 6] │
│ ``` │
│ │
│ --- │
│ │
│ ### filter │
│ │
│ ```lux │
│ fn filter<A>(list: List<A>, pred: fn(A): Bool): List<A> │
│ ``` │
│ │
│ Returns elements where `pred` returns true. │
│ │
└─────────────────────────────────────────────────────────────────────┘
Sections:
- Stdlib (List, String, Option, Result, Math, Json)
- Effects (Console, File, Process, Http, HttpServer, Time, Random, State, Fail, Sql, Postgres, Concurrent, Channel, Test)
- Spec (Grammar, Operators, Keywords)
7. Playground (/play)
Full-page playground:
┌─────────────────────────────────────────────────────────────────────┐
│ Lux Playground [Examples ▾] [Share] │
├─────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────┐ ┌────────────────────────────────┐ │
│ │ │ │ Output │ │
│ │ fn main(): Unit with ... │ │ │ │
│ │ │ │ > Hello, Lux! │ │
│ │ │ │ │ │
│ │ │ │ │ │
│ │ │ ├────────────────────────────────┤ │
│ │ │ │ Type Info / AST │ │
│ │ │ │ │ │
│ │ │ │ main: () -> Unit with Console │ │
│ │ │ │ │ │
│ └─────────────────────────────┘ └────────────────────────────────┘ │
│ │
│ [Run ▶] [Format] [Clear] │
└─────────────────────────────────────────────────────────────────────┘
Features:
- Syntax highlighting
- Error highlighting
- Examples dropdown
- Share via URL
- Format code
- View type info / AST (advanced)
Implementation Plan
Phase 1: Foundation (Week 1)
Homepage:
- Hero section with tagline
- Problem/solution comparison
- Three pillars with code examples
- Embedded playground (5 examples)
- Install instructions with copy buttons
- Trust badges
- Responsive navigation
- Footer
Install Page:
- Multi-platform instructions (Nix, source)
- Copy buttons
- Verification steps
Phase 2: Tour (Week 2)
Tour Infrastructure:
- Tour page template
- Code editor component
- Output panel
- Navigation (prev/next)
- Contents dropdown
- Progress indicator
Tour Content (12 lessons):
- Lesson 1-4: Basics (hello, values, functions, types)
- Lesson 5-6: Pattern matching and effects intro
- Lesson 7-9: Effects deep dive (using, custom, testing)
- Lesson 10-12: Modules, behavioral types, compilation
Phase 3: Examples (Week 3)
Examples Infrastructure:
- Category sidebar
- Example page template
- Navigation (prev/next within category)
Examples Content (40+ examples):
- Basics (10 examples)
- Types (5 examples)
- Effects (7 examples)
- Data (6 examples)
- Concurrent (4 examples)
- Web (4 examples)
Phase 4: Documentation (Week 4)
API Reference:
- Sidebar navigation
- Function documentation template
- Search functionality
- Stdlib documentation
- Effects documentation
Language Spec:
- EBNF grammar
- Operator precedence table
- Reserved words list
Phase 5: Deep Dives & Projects (Week 5-6)
Guides:
- Effects guide
- Behavioral types guide
- Compilation guide
- "Coming from X" guides
Projects:
- Todo API (complete source + tests)
- CLI Tool
- Web Scraper
Phase 6: Polish (Week 7-8)
- Mobile optimization
- Dark/light theme toggle
- Accessibility audit
- Performance optimization
- SEO meta tags
- Open Graph images
- Community page
- Blog infrastructure
Technical Stack
Option A: Pure HTML/CSS/JS
- No build step
- Fast page loads
- Easy to maintain
- Playground: server-side execution via API
Option B: Lux Static Site Generator
- Dogfooding (Lux builds its own site)
- Demonstrates language capabilities
- More complex but great marketing
Recommendation: Start with Option A, migrate to Option B once Lux is more mature.
Playground Implementation:
- Server-side: API endpoint calls
luxbinary - Future: WASM compilation for client-side execution
Design System
Colors:
--bg-primary: #0a0a0a; /* Near-black */
--bg-secondary: #111111;
--bg-glass: rgba(255,255,255,0.03);
--text-primary: #ffffff;
--text-secondary: rgba(255,255,255,0.7);
--gold: #d4af37; /* Accent */
--gold-light: #f4d03f;
--code-bg: rgba(212,175,55,0.05);
Typography:
--font-heading: "Playfair Display", Georgia, serif;
--font-body: "Source Serif Pro", Georgia, serif;
--font-code: "JetBrains Mono", monospace;
Aesthetic: Sleek and noble - black/gold, serif typography, generous whitespace.
Success Metrics
| Metric | Target |
|---|---|
| Time to first run (playground) | < 30 seconds |
| Time to local install | < 2 minutes |
| Tour completion rate (lesson 5) | > 50% |
| Tour completion rate (all 12) | > 25% |
| Return visitors (within week) | > 30% |
| Examples page views | > 500/month |
Appendix: Tagline Options
Problem-focused (recommended):
- "Side Effects Can't Hide"
- "Know What Your Code Does"
Benefit-focused:
- "Test Without Mocks"
- "Refactor With Confidence"
Feature-focused:
- "First-Class Effects"
- "Functional with Effects"
Recommended: "Side Effects Can't Hide" - memorable, problem-focused, differentiating