McCal Media Website

This repository contains the source code and documentation for the McCal Media website. The main site is built with Vite and serves as the public-facing portfolio and project hub. Legacy widget code is archived and no longer the focus of development.

Quick Start

Requirements: Node.js 20.19+ and npm.

1. Install dependencies: npm install
2. Start the dev server for the production site: cd sites/mcc-cal-vite && npm run dev
3. Open http://localhost:5173 to view the site.

Project Structure

• sites/mcc-cal-vite/ — Production site (Vite + React, main public site)
• sites/mcc-cal-admin/ — Admin console (Vite + React, Vercel auth and admin APIs)
• src/ — Shared source content and assets, including portfolio images and blog content
• docs/ — Documentation, standards, and migration notes
• scripts/ — Build, manifest, and utility scripts

Development

Available Scripts:

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build
• npm run lint - Run ESLint
• npm run test:e2e - Run end-to-end tests
• cd sites/mcc-cal-vite && npm run test:run - Run public app unit/API tests

Code Quality:

• TypeScript for type safety
• ESLint for code standards
• Prettier for formatting
• Component-based architecture with React

Performance Features:

• Lazy loading for large components
• Image optimization and CDN delivery
• Skeleton loaders for portfolio grids
• Code splitting for better bundle sizes

Sites

• Production Site (sites/mcc-cal-vite): The main site, built with Vite. All new public content and features are developed here.
• Admin Console (sites/mcc-cal-admin): Internal operations app for health, bookings, content, and settings surfaces.

Legacy Widgets (Archived)

Legacy widget code and documentation are archived. All new public-site development is focused on the Vite site.

Documentation

• docs/ — All documentation, standards, and migration notes
• docs/standards/ — Coding, performance, and accessibility standards
• docs/2026-COMPLETE.md, docs/2026-READY.md — Project status and migration notes

Development Workflow

• Run npm install at the repo root, then npm run dev for the main site
• Use npm run dev:admin for the admin console
• Use npm run dev:api for the local public-site API shim, or cd sites/mcc-cal-vite && npm run dev:vercel when testing Vercel Functions
• Run manifest/image scripts as needed for portfolio updates
• CDN-hosted manifests (no API required): see docs/manifest-cdn.md for jsDelivr URLs and the publish workflow.
• End-to-end portfolio manifest pipeline: see docs/workflows/portfolio-manifest-pipeline.md.

CI webhook notifications for manifests

Manifest workflows notify the API (if secrets set) so caches can be warmed automatically.

• Composite action: /.github/actions/notify-manifest-webhook centralizes webhook logic.
• Secrets required: MANIFEST_WEBHOOK_URL (or MANIFEST_WEBHOOK_BASE) and WEBHOOK_SECRET. If absent, notification step is skipped safely.

Blog Workflow

• Canonical blog source: src/content/blog/
• Authors: src/content/blog/authors.json
• Preferred authored post source: src/content/blog/posts/<slug>/post.md
• Generated runtime post document: src/content/blog/posts/<slug>/post.json
• Compile Markdown posts and rebuild the blog manifest: npm run manifest:blog
• Compile Markdown posts only: npm run blog:compile
• Validate blog authors, post metadata, and referenced local assets: npm run blog:validate
• Generate JSON/RSS feeds: npm run blog:feed
• Run the full blog publish prep (compile, validate, manifest, feeds): npm run blog:generate
• Migrate existing JSON posts to Markdown: npm run blog:migrate-markdown
• Import Google Docs into canonical blog posts: npm run blog:sync-docs

Deployment

• Production site (sites/mcc-cal-vite) is deployed via Vercel or static hosting.
• Admin console (sites/mcc-cal-admin) is deployed separately with noindex headers.
• Manifest CDN publishing remains in this repo. Cloudflare Worker/API deployment should happen from the companion API repository when that source is available.

Contributing

This is a personal project. No outside contributors are accepted at this time.

License

See LICENSE for details.

---

Legacy Widget Notes

Squarespace-era widgets are no longer the active development surface. Keep new work in the Vite app unless a legacy embed specifically needs maintenance.

Widget Release

We use tag-based releases for deploying widgets to Squarespace via jsDelivr:

• Tag format: widget-name@MAJOR.MINOR.PATCH (e.g., interactive-thesis@0.4.0)
• Pre-publish CI: archived widget workflows live under .github/workflows/archive/.
• CDN pattern: https://cdn.jsdelivr.net/gh/<owner>/<repo>@<tag>/<path-to-versioned-html>
• Example: https://cdn.jsdelivr.net/gh/McCal-Codes/McCals-Website@interactive-thesis@0.4.0/src/widgets/interactive-thesis/versions/v0.4-thesis-blog-format.html

Fixing archived widget validation errors:

1. Run locally: node scripts/utils/validate-widget-html.js
2. Read error output for offending files.
3. Update HTML per docs/standards/widget-standards.md.
4. Commit & push; CI re-validates.

🆕 Recent Organizational Highlights

• Test files consolidated under tests/
• Docs categorized (workflows, automation, integrations, standards, etc.)
• Widget status clarity (archives, WIP markers)
• Root directory cleaned (legacy test artifacts removed)

Widget Catalog

Production:

• Concert Portfolio — performance + SEO reference (v4.x line)
• Event Portfolio — dynamic category & shuffle (v2.6.x)
• Featured Portfolio — curated highlights
• Photojournalism Portfolio — news/journalism (v5.x in progress)
• Portrait Portfolio — vertical composition (v1.x)
• Video Portfolio — accessible multimedia (v0.1)
• About Page / Client Carousel — bio & logos
• Podcast Feed — auto-hydrating episodes
• Hero Slideshow — landing hero sections
• Site Footer — accessible glass footer
• Hire to Unlock Résumé — interactive résumé experience
• Admin Portfolio Importer — private image ingestion tool

Work In Progress:

• Photojournalism Portfolio v5.1 optimization
• Blog Feed integration
• Nature Portfolio gallery

Development Standards

Performance Regression CI:

• A headless Playwright-based performance scaffold runs basic metrics for widgets and uploads HTML reports. Lighthouse integration will be added in a subsequent iteration.

Quick Reference: docs/standards/widget-reference.md Architecture & Patterns: docs/standards/widget-standards.md Code Annotations: docs/standards/code-annotations.md — TODO, FIXME, BUG, SECURITY, and other annotation keywords Enhancements: docs/standards/widget-enhancements.md Performance: docs/standards/performance-standards.md SEO Starter: docs/standards/seo-starter-guide.md Image SEO: docs/standards/image-seo-standards.md

Using Widgets in Squarespace (Summary)

1. Copy latest version HTML from src/widgets/<name>/versions/
2. Paste into a Squarespace Code Block
3. Adjust data attributes (see widget README)
4. Regenerate manifests after adding images
5. Validate with the relevant archived/manual widget validator if restoring widget work

Important Notes

Security & recovery events: docs/important-notes/ (latest: 2025-10-09-secret-removal.md)

• Photojournalism Portfolio v5.1 (src/widgets/photojournalism-portfolio/versions/v5.1-performance-optimized.html) - Performance optimization pass in development
• Blog Feed (src/widgets/blog-feed/) - External blog integration (in development)
• Nature Portfolio (src/widgets/nature-portfolio/) - Nature photography displays (in development)

Archived Widgets in Squarespace

1. Navigate to src/widgets/[widget-name]/versions/
2. Copy the latest version HTML file (e.g., v4.1.0.html)
3. In Squarespace, add a Code Block
4. Paste the widget HTML code
5. Adjust data-panes or other attributes as needed
6. Each widget has its own README with specific instructions

Widget Development Standards ⭐ NEW

• Quick Reference: docs/standards/widget-reference.md - Essential checklist for widget development
• Complete Guide: docs/standards/widget-standards.md - Comprehensive architecture and design standards
• Enhancement Patterns: Proven improvement patterns for optimizing existing widgets
• SEO Testing Guide: docs/standards/seo-testing-guide.md - Comprehensive SEO testing and validation methods
• SEO Starter Guide: docs/standards/seo-starter-guide.md - Practical Squarespace SEO playbook for McCal Media

Development & Testing

Common scripts:

• npm run dev — Start the local dev server
• npm run build — Build the test site
• npm run preview — Preview the built public site
• npm run repo:health — Repository health checks
• npm run lint — ESLint
• npm run test — Playwright tests

Quick task aliases:

Script	What it does
npm run ai:preflight:short	Fast context/standards preflight (no writes)
npm run dev	Serve the public Vite site at http://localhost:5173
npm run dev:admin	Serve the admin console at http://localhost:4310
npm run manifest:dry-run	Dry-run manifest generation (no writes)
npm run repo:health	Clean + preflight + large-file scan

Contributing

• See CONTRIBUTING.md for branching, testing, and review expectations.
• Contributions are expected to follow our Code of Conduct.
• Repository-wide improvement roadmap: docs/repo-improvement-plan.md.

Documentation

Widget Documentation:

• See docs/widgets/index.md for per-widget usage summaries and links.

Full documentation lives in docs/README.md and includes:

• Standards: docs/standards/
• Workflows: docs/workflows/
• Automation: docs/automation/
• Integrations: docs/integrations/
• Deployment: docs/deployment/
• Tutorials: docs/tutorials/

Important Notes

Security and recovery events are tracked in docs/important-notes/. The latest entry is 2025-10-09-secret-removal.md.