andymadge.github.io Development Guidelines

Auto-generated from all feature plans. Last updated: 2025-11-25

Active Technologies

• Ruby / Jekyll 3.9+ (GitHub Pages gem), JavaScript ES6+, Liquid templates, SCSS + WaveSurfer.js v7 (jsDelivr CDN @7), BBC audiowaveform CLI (waveform generation, dev-time only), ffprobe (duration extraction, optional dev-time), HTML5 Audio API (browser-native) (001-dj-mix-hosting)
• Jekyll collection files (_djmixes/*.md YAML front matter), browser localStorage (playback positions, LRU cap 20 mixes), filesystem binary assets (assets/djmixes/{slug}/waveform.dat) (001-dj-mix-hosting)
• Ruby (Jekyll 3.9+ via GitHub Pages gem), JavaScript ES6+ + WaveSurfer.js v7 (jsDelivr CDN @7), BBC audiowaveform CLI (waveform generation, dev-time only), ffprobe (duration extraction, dev-time optional) (001-dj-mix-hosting)
• Jekyll collection files (_djmixes/*.md YAML front matter); browser localStorage (playback positions, LRU cap 20 mixes); filesystem binary assets (assets/djmixes/{slug}/waveform.dat) (001-dj-mix-hosting)
• Ruby 3.x / Jekyll 3.9+ (GitHub Pages gem); Liquid templating; HTML5 + Jekyll (via github-pages gem) — no new dependencies (002-mix-download-link)
• YAML front matter in _djmixes/*.md files (new optional field audio_download_url) (002-mix-download-link)
• Ruby 3.x / Jekyll 3.9+ (via github-pages gem); Liquid templates; HTML + Minimal Mistakes theme v4.19.3 (remote); Disqus (already configured, shortname: andymadge) (003-disqus-djmix)
• JavaScript ES6+ (browser), Ruby 3.x / Jekyll 3.9+ (build) + WaveSurfer.js v7.12.1 (jsDelivr CDN, pinned), HTML5 Audio API (browser-native) (004-safari-audio-fix)
• Ruby 3.x / Jekyll 3.9+ (GitHub Pages gem), Liquid templates, SCSS + WaveSurfer.js v7 (unchanged), Jekyll (unchanged) (005-tracklist-numbers)
• N/A — numbers are derived from loop position, not stored (005-tracklist-numbers)
• Ruby 3.x / Jekyll 3.9+ (GitHub Pages gem); SCSS + Jekyll + Minimal Mistakes theme v4.19.3 (remote); existing _sass/music-player.scss (006-fix-firefox-download-icon)
• JavaScript ES6+ (browser); Ruby 3.x / Liquid (Jekyll build-time) + Existing AudioPlayer, TrackHighlighter, navigator.mediaSession Web API (already wired in _layouts/mix.html; no new deps) (007-ios-media-metadata)
• Ruby 3.x / Jekyll 3.9+ (GitHub Pages gem); JavaScript ES6+ (browser) + Minimal Mistakes theme v4.19.3 (remote); WaveSurfer.js v7 (existing, unchanged) (008-google-analytics)
• Browser cookie (analytics_consent, 12-month expiry, SameSite=Lax) (008-google-analytics)
• Ruby 3.x / Jekyll 3.9+ (GitHub Pages gem) + Minimal Mistakes theme v4.19.3 (remote), Jekyll Liquid templates (009-privacy-policy)
• Static Markdown file in _pages/ with YAML front matter (009-privacy-policy)
• Ruby 3.x / Jekyll 3.9+ (GitHub Pages gem); Liquid templating + Minimal Mistakes theme v4.19.3 (remote); no new dependencies (010-mix-home-screen)
• YAML front matter in _djmixes/*.md files (010-mix-home-screen)
• Ruby 3.x / Jekyll 3.9+ (GitHub Pages gem); SCSS + Minimal Mistakes theme v4.19.3 (remote); existing _sass/music-player.scss (011-square-cover-images)
• Ruby 3.x / Jekyll 3.9+ (GitHub Pages gem); Liquid templates + Minimal Mistakes theme v4.19.3 (remote); jekyll-seo-tag (via theme) (012-cover-share-image)

• YAML front matter in _djmixes/*.md files (012-cover-share-image)

• Ruby 2.x+ (Jekyll 3.9+), JavaScript (ES6+), HTML5, CSS3 (001-dj-mix-hosting)

Project Structure

_djmixes/          # Jekyll collection: one .md file per mix
_layouts/          # mix.html, mix-index.html
_includes/         # audio-player.html, tracklist.html, mix-cover.html, mix-image.html, wavesurfer-loader.html
_sass/             # music-player.scss
assets/js/         # audio-player.js, playback-persistence.js, track-highlighter.js
assets/djmixes/    # per-mix waveform .dat files
scripts/           # add-mix.sh, generate-waveforms.sh

Commands

Development server (native Ruby — preferred):

bundle install             # first time or after Gemfile changes
bundle exec jekyll serve --livereload  # start dev server at http://localhost:4000

Development server (Docker — alternative):

docker compose up          # start dev server at http://localhost:4000
docker compose up --build  # rebuild image first (after Gemfile changes)
docker compose down        # stop

Build only (native):

bundle exec jekyll build

Build only (Docker):

docker compose run --rm jekyll bundle exec jekyll build

Code Style

Ruby (Jekyll 3.9+), JavaScript ES6+, Liquid, SCSS: follow standard conventions for each language

Recent Changes

• 012-cover-share-image: Added Ruby 3.x / Jekyll 3.9+ (GitHub Pages gem); Liquid templates + Minimal Mistakes theme v4.19.3 (remote); jekyll-seo-tag (via theme)
• 011-square-cover-images: Added Ruby 3.x / Jekyll 3.9+ (GitHub Pages gem); SCSS + Minimal Mistakes theme v4.19.3 (remote); existing _sass/music-player.scss
• 010-mix-home-screen: Added Ruby 3.x / Jekyll 3.9+ (GitHub Pages gem); Liquid templating + Minimal Mistakes theme v4.19.3 (remote); no new dependencies