Deploying to GitHub Pages
Relevant source files
The following files were used as context for generating this wiki page:
The norm project utilizes GitHub Pages to host several static versions of The Norm Macdonald Archive. The deployment strategy is centered around serving static files (HTML, CSS, JavaScript, and JSON data) directly from specific directories within the repository. This allows for multiple designs and prototypes to be publicly accessible from a single repository.
The repository contains different site versions, including a main static build, a redesigned prototype, and a "Codex-inspired" interface. Each version is self-contained within its own directory and is served as a sub-path of the main GitHub Pages URL for the repository.
Sources: README.md, redesign/README.md, codex-design/index.html
Repository Structure and Live URLs
The project is structured to serve content from multiple top-level directories. When published via GitHub Pages, each of these directories becomes a publicly accessible path.
Sources: README.md:21-22, README.md:37-39, redesign/README.md:31-32
The following diagram illustrates how repository directories map to live GitHub Pages URLs.
Sources: README.md, redesign/README.md, codex-design/index.html
URL Mapping
| Directory | Live URL Path | Description |
|---|---|---|
redesign/ | .../norm/redesign/ | A redesigned prototype of the Jokes section, built with vanilla HTML/CSS/JS. |
codex-design/ | .../norm/codex-design/ | An alternate "Codex-inspired" interface for exploring the joke archive. |
site/ | .../norm/site/ | Contains the generated static assets from a local build, likely the main version of the site. |
Sources: README.md:21-22, README.md:37-39, redesign/README.md:31-32
Deployment Workflows
Two distinct deployment workflows are evident in the repository: a direct static file deployment for simple HTML/CSS/JS projects and a build-based process for a legacy React application.
Standard Static File Deployment
The redesign and codex-design sites are built with vanilla HTML, CSS, and JavaScript, requiring no build tooling. Deployment for these versions is implicit: any changes pushed to their respective directories in the main branch are automatically published and reflected on the live GitHub Pages site.
Sources: redesign/README.md:34-37, README.md:49-51
Legacy React App Deployment
An older version of the website, located in old/site-src/, was built using React and requires a build process before deployment. The generated static assets from this build are intended to be placed in the root site/ directory for hosting.
Sources: old/site-src/TODO.txt, README.md:21-22
The following diagram shows the build and deployment process for this legacy application.
Sources: old/site-src/TODO.txt:10-13, README.md:21-22
The specific steps outlined for this process are as follows:
| Step | Command / Action | Description |
|---|---|---|
| 1 | cd /home/ubuntu/norm-macdonald-website | Navigate to the React app's source directory. |
| 2 | pnpm run build | Build the React application, which generates static assets in a dist folder. |
| 3 | cp /home/ubuntu/consolidated_youtube_data.json dist/ | Copy the main video data file into the build output directory. |
| 4 | Use deploy_frontend tool | A tool mentioned for deployment. Its exact function is not detailed, but it likely automates copying build artifacts. |
| 5 | Copy dist contents to site/ | The final step is to move the generated assets into the site/ directory of the Git repository to be served by GitHub Pages. |
Sources: old/site-src/TODO.txt:10-13, README.md:21-22
A TODO.txt file provides a concise command sequence for this deployment:
# QUICK DEPLOY COMMANDS:
cd /home/ubuntu/norm-macdonald-website
pnpm run build
cp /home/ubuntu/consolidated_youtube_data.json dist/
# Then use deploy_frontend tool
Sources: old/site-src/TODO.txt:18-22
Data Management for Deployment
A critical aspect of the site's content is the consolidated_youtube_data.json file, which contains data for 939 videos. The deployment process includes steps to ensure this data is up-to-date. The PLAYLIST_EXTRACTION_GUIDE.md outlines a workflow for developers to update this file locally and push it to the repository.
This pre-deployment data update workflow is crucial for keeping the video archive current.
The following sequence diagram illustrates the data update and commit process.
Sources: PLAYLIST_EXTRACTION_GUIDE.md
Once the updated consolidated_youtube_data.json is pushed to the repository, it becomes available to the static sites served by GitHub Pages, particularly the videos.html page which fetches this file to render the video list.
Sources: PLAYLIST_EXTRACTION_GUIDE.md:52-56, videos.js:63-66