Podsite

A sleek, modern podcast website built with Next.js and static export. Features a landing page with a featured episode, a full episodes list (20 mocked), episode detail pages, About, and FAQ sections.

Quick Start

Install dependencies

npm ci

Development server

npm run dev

Open http://localhost:3000 to view the site with live reload.

Build static site

npm run build

Runs validation, builds the Next.js project, and exports static HTML/CSS/JS to out/.

Preview static build locally

npm run preview

Serves the static out/ directory on http://localhost:5000.

Content & Episodes

Adding/editing episodes

Episodes are stored as markdown files with YAML frontmatter in src/content/episodes/. Each episode file is named ep-XXX.md (e.g., ep-001.md).

Required frontmatter fields:

• id: unique slug (e.g., "ep-001")
• title: episode title
• date: ISO 8601 date (e.g., "2025-01-01")
• description: short summary
• audio_url: path to audio file (e.g., /assets/audio/ep-001.mp3)

Optional fields:

• duration: human-readable (e.g., "28:34")
• artwork: path to image (e.g., /assets/images/ep-001.jpg)
• guests: array of guest names
• tags: array of tags
• featured: boolean (only one episode should be true)

Example episode file (src/content/episodes/ep-001.md):

---
id: "ep-001"
title: "Pilot: The Sound of Start"
date: "2025-01-01"
duration: "28:34"
description: "Short summary of episode content."
artwork: "/assets/images/ep-001.jpg"
audio_url: "/assets/audio/ep-001.mp3"
guests:
  - "Guest One"
tags:
  - "intro"
featured: true
---

Full show notes and transcript excerpts go in the markdown body below the frontmatter.

Assets

• Images: public/assets/images/ (episode artwork, etc.)
• Audio: public/assets/audio/ (episode MP3 files)

Scripts

• npm run dev — Start dev server with live reload
• npm run build — Validate, build, and export static site
• npm run preview — Serve static out/ locally
• npm run lint — Run ESLint and Prettier
• npm run lint:fix — Fix linting and formatting issues
• npm test — Run tests

Structure

podsite/
├── src/
│   ├── pages/              # Next.js pages (routes)
│   ├── components/         # React components
│   ├── styles/            # CSS files and tokens
│   └── content/
│       └── episodes/      # Episode markdown files
├── public/
│   └── assets/
│       ├── images/        # Episode artwork
│       └── audio/         # Episode audio files
├── scripts/               # Build scripts
├── specs/                 # Feature specs and documentation
└── package.json

Performance & Accessibility

• Target initial page load: ≤ 1.5 MB (uncompressed)
• Images should be optimized (WebP, AVIF, or compressed JPEG/PNG)
• All pages include language attribute and proper heading structure
• Images must include descriptive alt text
• Run npm run lint before committing

Deployment

See DEPLOYMENT.md for hosting and headers guidance.

Development

Adding a new page

Create a file in src/pages/ (e.g., src/pages/new-page.js). Next.js uses file-based routing:

• src/pages/index.js → /
• src/pages/about.js → /about
• src/pages/episodes/index.js → /episodes
• src/pages/episodes/[id].js → /episodes/:id

Styling

Global styles are in src/styles/global.css. Component-scoped styles use CSS modules or inline styles. Design tokens (colors, typography) are defined in src/styles/vars.css.

Contributing

1. Create a feature branch
2. Make changes and test locally with npm run dev
3. Run npm run lint:fix to fix formatting
4. Run npm run build to validate and build
5. Open a pull request

The CI will run lint, validation, build, and tests on each PR.

License

MIT