Project History
Relevant source files
The following files were used as context for generating this wiki page:
The Norm Macdonald Archive project has undergone several significant architectural and design iterations. It began as a static site, evolved into a single-page application using React, and has since seen multiple redesign prototypes using vanilla HTML, CSS, and JavaScript. The core purpose has remained consistent: to be a fan-made tribute that preserves and celebrates the comedic legacy of Norm Macdonald.
The project's history can be traced through distinct versions, each with its own technology stack and feature set. The original site was built by a user named "magus," and subsequent development has focused on enhancing the user experience, improving the design, and exploring different front-end technologies.
Sources: README.md:21, about.html:100-103
Project Evolution Stages
This diagram illustrates the major versions of the project as found in the repository.
Version 1: React Single-Page Application (old/)
An early version of the tribute site was a single-page application (SPA) built with React. This version is located in the old/ directory and was designed to be a comprehensive portal with multiple sections managed within a single component.
Sources: old/site-src/TODO.txt:3, old/site-src/App.jsx
Architecture and Components
The application's core logic is contained within App.jsx. It uses React hooks (useState, useEffect) to manage application state, such as the currently active section and a randomly displayed joke. The UI is composed of components from a custom library (@/components/ui/) for elements like buttons, cards, and tabs.
The main App component acts as a router, conditionally rendering different section components (JokesSection, VideosSection, TranscriptsSection) based on the activeSection state.
Sources: old/site-src/App.jsx:1-10, 29, 65-70, 329-341
This diagram shows the component structure and state management within the React application.
Key Features
| Feature | Description | Source File |
|---|---|---|
| Single-Page Navigation | Uses React state to switch between Home, Jokes, Videos, and Transcripts sections without page reloads. | old/site-src/App.jsx:65-70 |
| Random Joke Generator | A useEffect hook fetches a random featured joke and updates it every 10 seconds. | old/site-src/App.jsx:54-62 |
| Component-Based UI | Utilizes reusable UI components for Cards, Buttons, Tabs, and Badges. | old/site-src/App.jsx:2-6 |
| Archive Statistics | The home page displays key statistics about the archive's content. | old/site-src/App.jsx:45-50, 203-213 |
| Mobile Responsiveness | Includes a separate navigation menu for mobile devices. | old/site-src/App.jsx:128-158 |
A TODO.txt file indicates that this version was considered complete and ready for deployment, with tasks like building the app and copying data files being the final steps.
Sources: old/site-src/TODO.txt:1-14
Version 2: "Codex" Design Prototype (codex-design/)
An alternate interface was developed under the codex-design/ directory. This version presents a different user experience for exploring the joke archive, inspired by a "Codex" theme. It is built with vanilla HTML, CSS, and JavaScript, removing the need for a build step.
Sources: README.md:25-28, 38-40
Architecture and Features
The Codex design is a single HTML file (codex-design/index.html) that dynamically loads and filters joke data.
- Spotlight Joke: A prominent section that displays a random joke, which can be shuffled by the user.
- Combined Filtering: Features a search bar along with dropdown filters for "Guest" and "Source" that work in conjunction to refine the list of jokes.
- Dynamic Rendering: Uses a
<template>element to define the structure for a joke card, which is then cloned and populated with data via JavaScript. - Light/Dark Theme: Includes a theme toggle that respects system preference and persists the user's choice.
Sources: README.md:30-36, codex-design/index.html:13-17, 24-29, 31-48, 50-53
This flowchart shows the user interaction for filtering jokes in the Codex design.
Sources: README.md:33-34, codex-design/index.html:38-48
Version 3: Modern Redesign Prototype (redesign/)
The most recent iteration is a prototype for a redesigned Jokes section, located in the redesign/ directory. This version focuses on a clean, modern aesthetic inspired by "Norm Macdonald Live" and is also built with pure HTML, CSS, and JavaScript.
Sources: redesign/README.md:3, 9-10, 29-32
Architecture and Features
This prototype is structured across multiple HTML files (index.html, jokes.html, videos.html, etc.) linked by a common stylesheet (styles.css) and individual JavaScript files for interactivity.
The key features of this redesign are:
| Feature | Description | Source File(s) |
|---|---|---|
| New Design | A clean, modern aesthetic with a light/dark theme toggle that respects system preference. | redesign/README.md:9-13, redesign/styles.css |
| Random Joke Generator | A prominent button opens a modal to display a random joke. | redesign/README.md:15-18, redesign/jokes.html:77-85 |
| Enhanced Search & Filter | Provides real-time search and filtering by guest on the jokes page. | redesign/README.md:20-22, redesign/jokes.html:88-125 |
| Pagination | The joke list is paginated, showing 10 jokes per page. | redesign/README.md:25 |
| Share Functionality | Users can share individual jokes. | redesign/README.md:18, 26 |
| Keyboard Shortcuts | R for a random joke and ESC to close the modal. | redesign/README.md:27 |
Sources: redesign/README.md:7-27
Theme Management
A notable feature across the newer static versions is a robust theme management script. It checks for a user's preference in localStorage and falls back to the system's prefers-color-scheme.
This sequence diagram shows how the theme is initialized on page load.
Sources: redesign/index.html:248-273
Summary
The project's history demonstrates a clear progression in front-end development approaches. It started with a content-rich React SPA, which provided a dynamic, app-like experience. Later, development shifted towards lighter, more performant static site generator (SSG) friendly prototypes using vanilla JavaScript. These newer versions (codex-design and redesign) prioritize fast load times, modern design principles, and enhanced user interactivity (like advanced filtering and theme switching) without the overhead of a JavaScript framework. This evolution reflects a trend towards optimizing for performance and maintainability in static web projects.
Sources: README.md:21, 38-40, redesign/README.md:29-32, old/site-src/App.jsx