static-site-development — Add Data-Driven Pages to Static Sites

Use when building or extending a self-hosted static website with data-driven content (music libraries, download galleries, resource lists) where the content changes independently of the page markup.

Core Pattern

JSON manifest (library.json or similar) — single source of truth for all content
Vanilla JS rendering — fetch the manifest, build DOM from it, no frameworks
Folder-based assets — organize by category/genre/type in subdirectories
Match existing theme — reuse the site's CSS framework, color tokens, nav, footer, dark/light toggle

When to Use

Adding a new content section to an existing static site
Content that changes frequently (add/remove items without editing HTML)
Filterable lists (by genre, category, tag)
Media players (audio, video) with play + download actions
Any page where a hand-maintained HTML list would be painful

When NOT to Use

Single static page with content that never changes — just write HTML
Sites that already use a framework (React, Vue, etc.) — use the framework's patterns
Pages requiring server-side rendering or auth — this is static-only

Implementation Checklist

Read the existing site's index.html to extract: CSS framework, color tokens, nav structure, footer, theme toggle JS
Create the page shell: same <head>, same nav, same footer, same theme toggle
Design the manifest schema — minimal fields, only what the UI needs
Build the JS: fetch manifest → build filters → render list → bind interactions
Add the nav link to index.html
Verify: curl the page, check 200, check JS renders

Common Patterns

Genre/Category Filters

Filter buttons built dynamically from unique values in the manifest
"All" button always present, active by default
Click handler: set active genre, re-render visible items
Empty state when no items match

Single Shared Media Player

One hidden <audio> or <video> element
Each row's play button sets src and calls play()
Track activeId — if same track clicked, toggle play/pause; if different, switch
Sync UI on play, pause, ended events
Playing row gets visual highlight (border, ring, background)

Download Links

Plain <a href="..." download> — no JS needed
download attribute suggests filename; server sets Content-Disposition for forced download

Theme Matching

Copy the site's <head> (Tailwind CDN config, font imports, custom CSS classes)
Copy the nav and footer verbatim, update the active nav link
Reuse the same dark/light toggle script
Use the same glass/gradient/color utility classes

Pitfalls

Browser can't list directories — a static site can't readdir server folders. Always use a manifest file; never try to discover files by scanning paths from JS.
Caching the manifest — append ?t= + Date.now() to the fetch URL during development. Switch to a versioned URL or short cache in production.
Autoplay policy — browsers block play() without user gesture. The play button click satisfies this; setting src then play() in the same click handler works.
Multiple audio elements — avoid per-row <audio> tags. One shared element is lighter and prevents accidental multi-play.
nginx byte ranges — for seeking in audio/video, nginx must serve Accept-Ranges: bytes. It does by default for static files; don't disable it.

Reference Files

references/music-page-pattern.md — full implementation of a music library page with genre folders, library.json, single audio player, and Tailwind theme matching

3.9 KiB Raw Permalink Blame History

static-site-development — Add Data-Driven Pages to Static Sites

Core Pattern

When to Use

When NOT to Use

Implementation Checklist

Common Patterns

Genre/Category Filters

Single Shared Media Player

Download Links

Theme Matching

Pitfalls

Reference Files

3.9 KiB

Raw Permalink Blame History