lazyslides 0.1.0

package/scaffold/CLAUDE.md

@@ -0,0 +1,283 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with this LazySlides project.
+
+## Presentation Authoring Workflow
+
+### Creating a new presentation
+
+1. Start with an outline — fill in `presentations/_template/outline.md` or use `/create-outline`
+2. Run `/new-presentation` — the slash command guides you through the full process
+3. Or manually: create `presentations/{name}/index.md` with YAML frontmatter
+
+### Adding slides
+
+1. Run `/add-slide` — picks template, gathers content, inserts at the right position
+2. Or manually: add a new `- template: ...` entry to the `slides:` array
+
+### Editing slides
+
+1. Read the presentation's `index.md`
+2. Modify the YAML for the target slide
+3. Run `pnpm run validate` to verify
+4. Run `pnpm run dev` to preview
+
+### Validating
+
+```bash
+pnpm run validate    # check all presentations
+pnpm run renumber    # update slide comment numbers
+```
+
+## YAML Schema Reference
+
+All presentations use this structure:
+
+```yaml
+---
+title: Deck Title            # required
+description: Subtitle
+author: Speaker Name
+theme: default
+transition: slide
+progress: true
+slideNumber: true
+show_footer: true
+slides:                      # required — array of slide objects
+  - template: content        # required on every slide
+    title: Slide Title
+    # ... template-specific fields
+    notes: |                 # optional speaker notes (all templates)
+      What to say during this slide
+---
+```
+
+**Do NOT include** `layout: presentation` — it is set automatically.
+
+### Template Fields
+
+Fields marked with `*` are required.
+
+#### `title` — Opening slide
+- `title`* — presentation title
+- `subtitle` — tagline or date
+- `author` — speaker name
+- `logo` — show logo (default: true)
+
+#### `section` — Chapter divider
+- `title`* — section name
+- `subtitle` — section description
+
+#### `content` — Standard bullets
+- `title`* — slide title
+- `lead` — intro paragraph above bullets
+- `text` — body paragraph
+- `items` — bullet list (supports nested lists)
+- `ordered_items` — numbered list (supports nested lists)
+- `reference` / `reference_link` — single source
+- `references` — multiple sources (array of `{name, link}`)
+
+#### `center` — Centered statement or image
+- `title` — optional heading
+- `text` — centered statement
+- `image` — centered image path
+- `image_alt` — alt text
+- `reference` / `reference_link` / `references`
+
+#### `hero` — Full-bleed background
+- `title`* — big headline
+- `text` — supporting text
+- `image` — background image path
+- `color` — hex fallback color (e.g., `"#1a1a2e"`)
+- `box_title` — overlay box heading
+- `box_text` — overlay box content
+- `box_items` — overlay box bullet list
+- `hide_footer` — hide footer on this slide
+
+#### `metrics` — Key statistics
+- `title`* — slide title
+- `subtitle` — description
+- `metrics`* — array of metric objects:
+  - `value`* — the number/percentage
+  - `label`* — what it measures
+  - `context` — small text below label
+  - `color` — `mint`, `coral`, `icy`, `amber` (default: mauve)
+- `reference` / `reference_link` / `references`
+
+#### `comparison` — Two-column table
+- `title`* — slide title
+- `left_header` — left column header
+- `right_header` — right column header
+- `rows`* — array of row objects:
+  - `left` — left cell content
+  - `right` — right cell content
+  - `left_icon` — show icon in left cell (true/false)
+  - `right_icon` — show icon in right cell (true/false)
+- `highlight` — `left`, `right` (default), or `none`
+- `reference` / `reference_link` / `references`
+
+#### `columns` — Side-by-side content
+- `title`* — slide title
+- `left_title` / `left_text` / `left_items`
+- `right_title` / `right_text` / `right_items`
+- `reference` / `reference_link` / `references`
+
+#### `quote` — Testimonial
+- `quote`* — the quotation text
+- `author` — who said it
+- `author_title` — their role/title
+- `reference` / `reference_link` / `references`
+
+#### `image-overlay` — Image with text box
+- `image`* — full background image path
+- `title` — overlay heading
+- `text` — overlay paragraph
+- `items` — overlay bullet list
+- `position` — text box position
+- `reference` / `reference_link` / `references`
+
+#### `code` — Code snippet
+- `title`* — slide title
+- `code`* — the code block (use `|` for multiline)
+- `language` — syntax highlighting language
+- `caption` — description below code
+- `reference` / `reference_link` / `references`
+
+#### `timeline` — Horizontal events
+- `title`* — slide title
+- `events`* — array of event objects:
+  - `date` — when it happened
+  - `title`* — event name
+  - `text` — event description
+- `reference` / `reference_link` / `references`
+
+#### `funnel` — Progressive narrowing
+- `title`* — slide title
+- `stages`* — array of stage objects:
+  - `label`* — stage name
+  - `text` — stage description
+- `reference` / `reference_link` / `references`
+
+#### `split` — 1/3 image + 2/3 content
+- `title`* — slide title
+- `text` — body text
+- `items` — bullet list (supports nested lists)
+- `image`* — image path
+- `image_alt` — alt text
+- `reference` / `reference_link` / `references`
+
+#### `split-wide` — 1/3 content + 2/3 image
+- `title`* — slide title
+- `text` — body text
+- `items` — bullet list (supports nested lists)
+- `image`* — image path
+- `image_alt` — alt text
+- `reference` / `reference_link` / `references`
+
+#### `table` — Data table
+- `title`* — slide title
+- `columns`* — array of column header strings
+- `rows`* — array of row arrays (each row is an array of cell strings)
+- `reference` / `reference_link` / `references`
+
+#### `agenda` — Clickable table of contents
+- `title` — slide title (default: "Agenda")
+- `sections`* — array of section objects:
+  - `title`* — section name
+  - `slide`* — slide number to link to
+- `reference` / `reference_link` / `references`
+
+## Common Patterns
+
+### Nested lists
+Supported in `content`, `split`, and `split-wide` templates:
+```yaml
+items:
+  - "Regular item"
+  - "Parent with children:":
+      - "Child 1"
+      - "Child 2"
+```
+
+### References
+```yaml
+# Single source
+reference: "McKinsey Digital 2024"
+reference_link: "https://..."
+
+# Multiple sources
+references:
+  - name: "Source 1"
+    link: "https://..."
+  - name: "Source 2"
+    link: "https://..."
+```
+
+### Speaker notes
+```yaml
+notes: |
+  Key talking points for this slide.
+  Press S in Reveal.js to open speaker view.
+```
+
+### Section comments
+Use YAML comments to number and label slides:
+```yaml
+slides:
+# Slide 1: Opening
+- template: title
+  title: My Talk
+
+# Slide 2: Agenda
+- template: agenda
+```
+
+### Image lightbox
+Images in `center`, `split`, and `split-wide` templates automatically get lightbox functionality via GLightbox. Click any image to view fullscreen.
+
+## Design System
+
+- **Dimensions:** 960x540 (16:9) — Reveal.js scales to fit viewport
+- **Typography:** Source Serif 4 for headings, Plus Jakarta Sans for body
+- **Colors:** Primary is mauve (purple), semantic colors: `mint`, `coral`, `amber`, `icy`
+- **Spacing:** 40px slide padding
+
+## Rules for Claude
+
+### DO
+- Read the template docblock before generating YAML for unfamiliar templates
+- Run `pnpm run validate` after any YAML changes
+- Use the map syntax for nested lists (parent string ends with colon, quoted)
+- Quote YAML strings containing colons, HTML, or special characters
+- Keep bullet points to 3-5 per slide
+- Use `section` templates to organize long presentations
+
+### DON'T
+- Add `layout: presentation` to frontmatter
+- Use raw HTML in YAML values
+- Create deeply nested lists (max 2 levels)
+- Use template names not in the valid list
+- Reference images that don't exist without marking them as TODOs
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/new-presentation` | Create a complete presentation from scratch |
+| `/add-slide` | Add a slide to an existing presentation |
+| `/validate` | Validate YAML and fix issues |
+| `/research-topic` | Research a topic for data-driven slides |
+| `/create-outline` | Create a structured outline before generating YAML |
+| `/refine-slides` | Review and improve an existing presentation |
+
+## Build Commands
+
+```bash
+pnpm run dev          # Development server with hot reload
+pnpm run build        # Production build
+pnpm run validate     # Validate presentation YAML
+pnpm run renumber     # Renumber slide comments
+pnpm run pdf          # Export to PDF
+```
+
+**Requirements:** Node.js 22 (see `.nvmrc`), install deps with `pnpm install`

package/scaffold/README.md

@@ -0,0 +1,29 @@
+# {{name}}
+
+A presentation project built with [LazySlides](https://github.com/chris-tietz/lazyslides).
+
+## Quick Start
+
+```bash
+pnpm install
+pnpm run dev
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `pnpm run dev` | Development server with hot reload |
+| `pnpm run build` | Production build |
+| `pnpm run validate` | Validate presentation YAML |
+| `pnpm run renumber` | Renumber slide comments |
+| `pnpm run pdf` | Export to PDF |
+
+## Creating Presentations
+
+Add a new folder under `presentations/` with an `index.md` file containing your slides in YAML format. See `presentations/_template/index.md` for a starter template.
+
+## Customization
+
+- **Themes** — Drop CSS files into `themes/` to override the default theme
+- **Styles** — Add custom CSS to `src/styles.css`

package/scaffold/_template/index.md

@@ -0,0 +1,78 @@
+---
+title: Presentation Title
+description: Brief description
+transition: slide
+
+slides:
+  - template: title
+    title: Presentation Title
+    subtitle: Subtitle or tagline
+    author: Your Name
+
+  - template: section
+    title: Section One
+
+  - template: content
+    title: Content Slide
+    text: Introduction to your topic
+    items:
+      - First key point
+      - Second key point
+      - Third key point
+
+  - template: center
+    title: Big Statement
+    text: A powerful quote or impactful statement.
+
+  - template: comparison
+    title: Before vs After
+    rows:
+      - left: Old way
+        right: New way
+      - left: "✗ Problem"
+        right: "✓ Solution"
+
+  - template: hero
+    title: Hero Title
+    image: images/hero.jpg
+    text: Overlay text on full-bleed image
+
+  - template: image-overlay
+    title: Context
+    image: images/diagram.png
+    position: bottom-left
+    text: Explanation of what the image shows.
+
+  - template: section
+    title: Section Two
+
+  - template: metrics
+    title: Key Metrics
+    metrics:
+      - value: "42%"
+        label: Metric One
+      - value: "3x"
+        label: Metric Two
+
+  - template: columns
+    title: Two Columns
+    left_title: Left Side
+    left_text: Content for the left column.
+    right_title: Right Side
+    right_text: Content for the right column.
+
+  - template: code
+    title: Code Example
+    language: python
+    code: |
+      def hello(name):
+          return f"Hello, {name}!"
+
+  - template: quote
+    quote: Your favorite quote here.
+    author: Attribution
+
+  - template: title
+    title: Thank You!
+    subtitle: Questions?
+---

package/scaffold/_template/outline.md

@@ -0,0 +1,32 @@
+# Presentation Title
+
+> This is the target format for LazySlides outlines. Any AI tool — Claude Code,
+> Claude Desktop, ChatGPT, or others — can convert research notes, meeting
+> transcripts, or any source material into this format. Save the completed
+> outline as `outline.md` in your presentation folder, then use it to generate
+> the final slide deck.
+
+## Metadata
+- **Audience:** [description]
+- **Purpose:** [goal]
+- **Speaker:** [name and background]
+- **Duration:** [estimated time]
+
+## Key Messages
+1. [message 1]
+2. [message 2]
+3. [message 3]
+
+## Outline
+
+### Section 1: [Section Name]
+Purpose: [why this section exists]
+
+#### Slide 1.1: [Slide Title]
+- **Key point:** [main takeaway]
+- **Template:** [template name]
+- **Notes:** [what to say]
+- **Visual idea:** [optional visualization concept]
+
+### Section 2: [Section Name]
+...

package/scaffold/claude-commands/add-slide.md

@@ -0,0 +1,61 @@
+# Add Slide
+
+You are helping the user add a new slide to an existing presentation.
+
+## Step 1: Identify Target Presentation
+
+List the presentation folders in `presentations/` (excluding `_template`). Ask the user which presentation they want to add a slide to. If there's only one, confirm it.
+
+## Step 2: Show Current Slides
+
+Read the presentation's `index.md` and display a numbered list of existing slides:
+
+```
+1. [title] Opening Slide
+2. [content] Key Points
+3. [metrics] Results
+```
+
+Ask the user where to insert the new slide (after which slide number, or at the end).
+
+## Step 3: Choose Template
+
+Ask the user which template to use. Show this reference:
+
+| Template | Best For |
+|----------|----------|
+| `title` | Opening slide with logo, title, subtitle, author |
+| `section` | Section divider for organizing chapters |
+| `content` | Standard bullet points with optional lead text |
+| `center` | Single statement or image, centered |
+| `hero` | Full-bleed background image with text overlay |
+| `metrics` | 2-4 key statistics with colored cards |
+| `comparison` | Before/after two-column table |
+| `columns` | Side-by-side content columns |
+| `split` | 1/3 image + 2/3 content |
+| `split-wide` | 1/3 content + 2/3 image |
+| `quote` | Testimonial with attribution |
+| `timeline` | Horizontal timeline with events |
+| `funnel` | Progressive narrowing funnel |
+| `table` | Data table with headers |
+| `code` | Code snippet with syntax highlighting |
+| `image-overlay` | Full image with positioned text box |
+| `agenda` | Clickable table of contents |
+
+## Step 4: Gather Content
+
+Based on the chosen template, read the docblock in `_includes/slides/{template}.njk` for the exact field reference. Ask the user for:
+- Required fields (marked with * in the docblock)
+- Optional fields they want to include
+- Speaker notes (optional)
+
+## Step 5: Generate and Insert
+
+1. Generate the YAML for the new slide
+2. Insert it at the correct position in the `slides:` array
+3. Run `pnpm run renumber` to update slide comments
+4. Run `pnpm run validate` to verify
+
+## Step 6: Preview
+
+Suggest the user run `pnpm run dev` to preview the result.

package/scaffold/claude-commands/create-outline.md

@@ -0,0 +1,75 @@
+# Create Outline
+
+You are helping the user create a structured outline before generating presentation YAML.
+
+## Step 1: Gather Context
+
+Ask the user for:
+1. **Topic** — what is the presentation about?
+2. **Audience** — who will watch this?
+3. **Purpose** — inform, persuade, teach, pitch, report?
+4. **Duration** — how long is the talk? (affects slide count: ~1 slide per minute)
+5. **Speaker** — name and relevant background
+
+## Step 2: Check for Existing Research
+
+Look for a `research.md` file in the target presentation folder. If it exists, use the findings to inform the outline. If not, proceed with the user's input.
+
+## Step 3: Draft Section Structure
+
+Based on the purpose, propose a structure:
+
+**Pitch:** Problem → Solution → Evidence → Differentiation → Ask
+**Teaching:** Context → Concepts → Examples → Practice → Summary
+**Report:** Overview → Findings → Analysis → Recommendations → Next Steps
+**Persuasion:** Status Quo → Problem → Vision → Proof → Call to Action
+
+Present the proposed sections and iterate with the user.
+
+## Step 4: Detail Each Slide
+
+For each slide in the outline, specify:
+- **Title** — clear, concise slide title
+- **Template** — which LazySlides template to use
+- **Key point** — the one takeaway from this slide
+- **Content sketch** — bullet points, data, or narrative
+- **Notes sketch** — what the speaker should say
+
+Read the docblock in `_includes/slides/{template}.njk` to verify field names.
+
+## Step 5: Save Outline
+
+Save as `outline.md` in the presentation folder:
+
+```markdown
+# [Presentation Title]
+
+## Metadata
+- **Audience:** [description]
+- **Purpose:** [goal]
+- **Speaker:** [name and background]
+- **Duration:** [estimated time]
+- **Slide count:** [estimated number]
+
+## Key Messages
+1. [message 1]
+2. [message 2]
+3. [message 3]
+
+## Outline
+
+### Section 1: [Name]
+
+#### Slide 1.1: [Title]
+- **Template:** [template]
+- **Key point:** [takeaway]
+- **Content:** [sketch]
+- **Notes:** [speaker notes]
+
+#### Slide 1.2: [Title]
+...
+```
+
+## Step 6: Next Steps
+
+Offer to generate the full presentation YAML from this outline — this follows the same flow as `/new-presentation` Step 5 onward.