Contribution Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• PLAYLIST_EXTRACTION_GUIDE.md
• README.md
• old/site-src/TODO.txt
• redesign/script.js
• redesign/README.md

This document outlines the guidelines and processes for contributing to The Norm Macdonald Archive. The project is a static, fan-made tribute site built with vanilla HTML, CSS, and JavaScript, designed to preserve and celebrate Norm Macdonald's work. Contributions primarily focus on expanding the archive's data, such as adding jokes and video metadata.

The project consists of several parts, including a main static site, a "redesign" prototype, and a "Codex-inspired" interface for exploring jokes. The core data for these pages is sourced from JSON files like jokes-data.json and consolidated_youtube_data.json. The following guidelines focus on the established process for adding new video data to the archive.

Sources: README.md, redesign/README.md, PLAYLIST_EXTRACTION_GUIDE.md

Adding Video Content

The primary method for contributing new content is by extracting video metadata from YouTube playlists and merging it into the main database file, consolidated_youtube_data.json. This process ensures that new videos appear on the site's video pages.

Sources: PLAYLIST_EXTRACTION_GUIDE.md, old/site-src/TODO.txt:10-11

Video Data Schema

When extracting video data, it must conform to a specific JSON structure. Each video should be an object within a larger array. The required fields are detailed below. While some fields can be populated with "N/A", the Video url and Title are essential.

Field	Type	Description	Example
Video url	String	The full YouTube watch URL.	"https://www.youtube.com/watch?v=VIDEO_ID"
Title	String	The title of the video.	"Video Title Here"
Description	String	A short description. Defaults to "Video url:".	"Video url:"
Channel name	String	The name of the YouTube channel. Can be "N/A".	"N/A"
Duration	String	The duration of the video. Can be "N/A".	"N/A"
Views	String	The view count. Can be "N/A".	"N/A"
Thumbnail url	String	The URL for the video thumbnail. Can be "N/A".	"N/A"

Sources: PLAYLIST_EXTRACTION_GUIDE.md:30-38, PLAYLIST_EXTRACTION_GUIDE.md:100-108

Playlist Extraction and Merging Workflow

The end-to-end process involves extracting data from a YouTube playlist, merging it with the existing consolidated data file, and committing the changes.

The following diagram illustrates the complete contribution workflow for adding new videos.

Extraction Methods

There are several methods available for extracting the video data into the required playlist_videos.json format. These are designed to be run on a local machine, as the development environment has network restrictions.

Sources: PLAYLIST_EXTRACTION_GUIDE.md:3, PLAYLIST_EXTRACTION_GUIDE.md:88-90

Method 1: Browser Console Script (Easiest)

This method requires no installation and is executed directly in the browser.

1. Navigate to the target YouTube playlist (e.g., https://youtube.com/playlist?list=PLxTIDernmMHuIsNqSMOhKR1jlWimaLklk).
2. Scroll to the bottom of the page to ensure all videos in the playlist are loaded.
3. Open the browser's developer console (F12 or Ctrl+Shift+J).
4. Paste and run the provided JavaScript snippet.

const videos = [];
const videoElements = document.querySelectorAll('ytd-playlist-video-renderer');

videoElements.forEach(video => {
    try {
        const titleElement = video.querySelector('#video-title');
        const linkElement = video.querySelector('a#thumbnail');
        if (titleElement && linkElement) {
            const url = linkElement.href;
            const videoId = new URL(url).searchParams.get('v');
            const title = titleElement.textContent.trim();
            videos.push({
                "Video url": `https://www.youtube.com/watch?v=${videoId}`,
                "Title": title,
                "Description": "Video url:",
                "Channel name": "N/A",
                "Duration": "N/A",
                "Views": "N/A",
                "Thumbnail url": "N/A"
            });
        }
    } catch (e) { console.error('Error:', e); }
});

console.log(JSON.stringify(videos, null, 2));
console.log(`Extracted ${videos.length} videos`);
copy(JSON.stringify(videos, null, 2));
console.log("✅ JSON copied to clipboard!");

1. The script will automatically copy the JSON output to your clipboard. Save this content into a file named playlist_videos.json.

Sources: PLAYLIST_EXTRACTION_GUIDE.md:10-43

Method 2: Python Script (Most Reliable)

This method uses a Python script and the pytube library.

1. Install pytube: pip install pytube
2. Run the extraction script: python3 extract_playlist.py
3. This will automatically generate the playlist_videos.json file.

Sources: PLAYLIST_EXTRACTION_GUIDE.md:47-55

Merging and Committing Data

After generating playlist_videos.json, the new data must be merged into the main database.

1. Run the Merge Script: Execute python3 merge_playlist_data.py.
2. Verification: The script will load the new videos, check for duplicates against consolidated_youtube_data.json, add only the new entries, and report the number of videos added.
3. Commit Changes: Once the merge is complete, add the updated consolidated_youtube_data.json file to a new commit.
4. Push: Push the commit to the appropriate branch.

The following diagram shows the sequence of operations performed by the merge script.

Other Contributions

While the primary contribution path is data-focused, the project also involves frontend development. The old/ directory contains a React-based application. The build and deployment process for this part of the site is as follows:

1. Navigate to the React app directory: cd /home/ubuntu/norm-macdonald-website
2. Build the application: pnpm run build
3. Copy the consolidated_youtube_data.json file into the dist/ folder.
4. Use the deploy_frontend tool to deploy the changes.

Sources: old/site-src/TODO.txt:9-12, old/site-src/TODO.txt:17-20

The redesign/ and codex-design/ sections are built with pure HTML, CSS, and JavaScript, without frameworks. Contributions to these sections would involve modifying the respective .html, .css, and .js files. For example, the interactive joke filtering logic is contained entirely within redesign/script.js.

Sources: redesign/README.md:28-31, redesign/script.js, README.md:48-52