lazyslides 0.1.0

package/scaffold/claude-commands/new-presentation.md

@@ -0,0 +1,218 @@
+# Create New Presentation
+
+You are helping the user create a new presentation in this Eleventy + Reveal.js presentation system.
+
+## Step 1: Gather Basic Information
+
+Ask the user for:
+1. **Presentation name** (required) - will be used for folder name (kebab-case)
+2. **Presentation date** (optional) - format: MMYYYY (e.g., 032026 for March 2026)
+
+Create the folder at `presentations/{name}-{date}/` or `presentations/{name}/` if no date provided.
+
+## Step 2: Check for Outline
+
+Ask the user if they have an `outline.md` file to supply.
+
+### If NO outline exists:
+
+Help them create one by gathering:
+
+1. **Audience** - Who will be watching this presentation?
+2. **Purpose** - What's the goal? (inform, persuade, teach, pitch, etc.)
+3. **Speaker background** - What gives the speaker credibility on this topic?
+4. **Key points** - What are the 3-5 main messages they want to convey?
+5. **Desired structure** - Do they have a mental model? (problem/solution, journey, comparison, etc.)
+6. **Time constraint** - How long is the presentation? (affects slide count)
+
+Use this information to draft an `outline.md` in the presentation folder with this structure:
+
+```markdown
+# [Presentation Title]
+
+## 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]
+- **Notes:** [what to say]
+- **Visual idea:** [optional visualization concept]
+
+#### Slide 1.2: [Slide Title]
+...
+
+### Section 2: [Section Name]
+...
+```
+
+### If outline IS supplied:
+
+Review it and confirm:
+- Does it have clear sections?
+- Does each slide have a key point?
+- Is there enough detail to select templates?
+
+If not, iterate with the user to fill in gaps.
+
+## Step 3: Map Slides to Templates
+
+Review each slide in the outline and propose a template. The available templates are in `_includes/slides/`:
+
+| Template | Best For |
+|----------|----------|
+| `title` | Opening slide with logo, title, subtitle, author |
+| `section` | Section dividers within the presentation |
+| `agenda` | Table of contents with clickable section links |
+| `content` | Standard bullet points with optional lead text |
+| `center` | Single impactful statement, centered |
+| `hero` | Full-bleed background image with big text |
+| `metrics` | 2-4 key statistics with colored cards |
+| `comparison` | Before/after or two-column comparison table |
+| `columns` | Side-by-side content columns |
+| `split` | 1/3 image + 2/3 content layout |
+| `split-wide` | 1/3 content + 2/3 image layout |
+| `quote` | Testimonial or quotation with attribution |
+| `timeline` | Horizontal timeline with events |
+| `funnel` | Sales/conversion funnel visualization |
+| `table` | Data table with headers |
+| `code` | Code snippet with syntax highlighting |
+| `image-overlay` | Image with text overlay |
+
+Read each template file's docblock comment for exact YAML structure and options.
+
+Present your template recommendations to the user in a table:
+
+```
+| Slide | Title | Proposed Template | Rationale |
+|-------|-------|-------------------|-----------|
+| 1.1   | ...   | title             | Opening   |
+```
+
+Iterate until the user approves. Then update `outline.md` with a `template:` field for each slide.
+
+## Step 4: Research & Enrichment (Optional)
+
+If the user wants, help enrich the outline with:
+- Statistics and citations
+- Industry data
+- Competitor analysis
+- Supporting examples
+
+Add references to the outline as you find them.
+
+## Step 5: Create index.md
+
+Once the outline is finalized, create `presentations/{folder}/index.md` with the full YAML frontmatter.
+
+### Required frontmatter structure:
+
+```yaml
+---
+title: [Presentation Title]
+description: [Subtitle or tagline]
+author: [Speaker Name]
+theme: default
+transition: slide
+progress: true
+slideNumber: true
+show_footer: true
+slides:
+# Slide 1: [Title]
+- template: [template_name]
+  title: [slide title]
+  # ... template-specific fields from docblock
+  notes: |
+    [speaker notes from outline]
+---
+```
+
+Note: Do NOT include `layout: presentation` — this is set automatically by the directory data file.
+
+### For each slide:
+
+1. Read the template docblock in `_includes/slides/{template}.njk`
+2. Map outline content to the template's required/optional fields
+3. Add speaker notes from the outline
+4. Add references if provided
+
+### Image handling:
+
+- Create an `images/` folder in the presentation directory
+- If visuals are specified in outline, note them in the YAML
+- If NO visuals are specified but the template needs an image (hero, split), create a placeholder:
+  - Create placeholder file: `images/placeholder-{slide-number}.jpg`
+  - Add a comment in the YAML: `# TODO: Replace placeholder image`
+  - Note in the slide's notes what kind of image would work
+
+## Step 6: Validate
+
+After creating `index.md`, run the validation:
+
+```bash
+pnpm run validate
+```
+
+Fix any errors before finishing.
+
+## Step 7: Preview
+
+Suggest the user run:
+
+```bash
+pnpm run dev
+```
+
+Then navigate to the presentation URL to preview.
+
+---
+
+## Template Quick Reference
+
+When creating slides, always read the full docblock in the template file. Here are the key patterns:
+
+### Nested lists (content, split, split-wide templates):
+```yaml
+items:
+  - "Regular item"
+  - "Parent with children:":
+      - "Child 1"
+      - "Child 2"
+```
+
+### References:
+```yaml
+reference: "Source Name 2025"
+reference_link: "https://..."
+# OR for multiple:
+references:
+  - name: "Source 1"
+    link: "https://..."
+  - name: "Source 2"
+    link: "https://..."
+```
+
+### Metrics colors:
+`mint`, `coral`, `icy`, `amber` (or omit for default mauve)
+
+### Comparison highlight:
+`highlight: left` | `highlight: right` (default) | `highlight: none`
+
+### Hero backgrounds:
+```yaml
+image: images/background.jpg
+# OR
+color: "#1a1a2e"
+```

package/scaffold/claude-commands/refine-slides.md

@@ -0,0 +1,62 @@
+# Refine Slides
+
+You are helping the user improve an existing presentation.
+
+## Step 1: Load and Validate
+
+1. Ask which presentation to refine (list `presentations/` folders)
+2. Read the presentation's `index.md`
+3. Run validation first:
+   ```bash
+   pnpm run validate
+   ```
+4. Fix any errors before proceeding
+
+## Step 2: Structural Analysis
+
+Analyze and report:
+- **Slide count** — is it appropriate for the estimated duration?
+- **Template diversity** — are templates varied or repetitive? (e.g., 10 `content` slides in a row)
+- **Visual rhythm** — is there a good mix of text-heavy and visual slides?
+- **Section structure** — are `section` dividers used to organize the flow?
+- **Notes coverage** — which slides are missing speaker notes?
+
+## Step 3: Content Review
+
+Check each slide for:
+- **Title quality** — clear, concise, action-oriented?
+- **Bullet density** — too many items per slide? (aim for 3-5)
+- **Nested list depth** — more than 2 levels deep is hard to read
+- **Quote length** — quotes should be impactful, not paragraphs
+- **Image paths** — do all referenced images exist?
+- **References** — are sources properly attributed?
+
+## Step 4: Prioritized Suggestions
+
+Present findings as a prioritized list:
+
+### High Priority
+- Issues that affect readability or correctness
+
+### Medium Priority
+- Template swaps that would improve visual variety
+- Slides that could be split or merged
+
+### Low Priority
+- Minor wording improvements
+- Optional enhancements (add speaker notes, add references)
+
+## Step 5: Apply Changes
+
+After the user approves specific suggestions:
+1. Apply the changes to `index.md`
+2. Run `pnpm run renumber` to update slide comments
+3. Run `pnpm run validate` to verify
+
+## Step 6: Summary
+
+Show a before/after comparison:
+- Slide count (before → after)
+- Template distribution
+- Issues resolved
+- Remaining suggestions (if any)

package/scaffold/claude-commands/research-topic.md

@@ -0,0 +1,66 @@
+# Research Topic
+
+You are helping the user research a topic to build a data-driven presentation.
+
+## Step 1: Gather Research Parameters
+
+Ask the user for:
+1. **Topic** — what is the presentation about?
+2. **Angle** — what perspective or thesis? (e.g., "why companies should adopt X")
+3. **Audience** — who will watch this? (affects depth and jargon level)
+4. **Depth** — quick overview (5-10 data points) or deep dive (20+)?
+
+## Step 2: Research
+
+Search the web for:
+- **Statistics** — recent numbers, percentages, growth rates
+- **Quotes** — expert opinions, notable statements
+- **Comparisons** — before/after, competitor analysis, benchmarks
+- **Timelines** — key events, milestones, evolution
+- **Case studies** — real-world examples with outcomes
+
+Prioritize recent sources (last 2 years). Always capture the source name, URL, and date.
+
+## Step 3: Organize Findings
+
+Structure findings into categories:
+
+```markdown
+## Key Statistics
+- [stat] — Source (Year)
+
+## Notable Quotes
+- "[quote]" — Author, Title (Source)
+
+## Comparisons
+- [comparison point] — Source
+
+## Timeline / Milestones
+- [date]: [event] — Source
+
+## Case Studies
+- [company/example]: [outcome] — Source
+```
+
+## Step 4: Save Research
+
+Save the organized findings as `research.md` in the target presentation folder:
+`presentations/{name}/research.md`
+
+## Step 5: Suggest Template Mapping
+
+For each finding, suggest which LazySlides template would best present it:
+
+| Finding | Suggested Template | Rationale |
+|---------|-------------------|-----------|
+| Key statistic | `metrics` | Numeric data with colored cards |
+| Quote | `quote` | Attribution and styling |
+| Comparison | `comparison` | Side-by-side table |
+| Timeline | `timeline` | Chronological events |
+| Case study | `split` or `content` | Narrative with supporting image |
+
+## Step 6: Next Steps
+
+Offer the user:
+- `/create-outline` to structure a full presentation from this research
+- `/add-slide` to add individual data points to an existing deck

package/scaffold/claude-commands/validate.md

@@ -0,0 +1,47 @@
+# Validate Presentations
+
+You are helping the user validate their presentation YAML and fix any issues.
+
+## Step 1: Run Validation
+
+```bash
+pnpm run validate
+```
+
+## Step 2: Interpret Results
+
+Review the output and categorize issues:
+
+### Errors (must fix)
+- **No valid YAML front matter** — missing `---` fences or malformed YAML
+- **Missing required field** — `title` or `slides` missing from frontmatter
+- **Missing template field** — a slide is missing the `template:` key
+- **Wrong comparison format** — comparison slides must use `rows:` with `left`/`right` pairs
+
+### Warnings (should fix)
+- **Unknown template** — template name doesn't match one of the 17 valid types
+- **Missing title** — slide has no title (except `quote` which doesn't need one)
+- **Missing image** — image path in YAML doesn't exist on disk
+- **Hidden slide** — possible slide definition commented out
+- **Slide count mismatch** — `expected_slides` doesn't match actual count
+
+## Step 3: Propose Fixes
+
+For each error:
+1. Explain what's wrong in plain language
+2. Show the problematic YAML
+3. Propose the corrected YAML
+
+For each warning:
+1. Explain the risk
+2. Suggest a fix or explain why it's safe to ignore
+
+## Step 4: Apply Fixes
+
+After the user approves, apply the fixes and re-run validation:
+
+```bash
+pnpm run validate
+```
+
+Repeat until all errors are resolved.

package/scaffold/claude-settings.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pnpm run:*)"
+    ]
+  }
+}

package/scaffold/eleventy.config.js

@@ -0,0 +1,11 @@
+import lazyslides from "lazyslides";
+
+export default function(eleventyConfig) {
+  eleventyConfig.addPlugin(lazyslides);
+
+  return {
+    dir: { input: ".", layouts: "_layouts", output: "_site" },
+    templateFormats: ["md", "njk"],
+    markdownTemplateEngine: "njk"
+  };
+};

package/scaffold/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+_site/
+.DS_Store
+_pdfs/
+*.log

package/scaffold/my-first-deck/index.md

@@ -0,0 +1,26 @@
+---
+title: My First Deck
+description: A hello world presentation
+transition: slide
+
+slides:
+  - template: title
+    title: My First Deck
+    subtitle: Built with LazySlides
+
+  - template: content
+    title: Getting Started
+    lead: Edit this file to build your presentation
+    items:
+      - Each slide is a YAML object with a template field
+      - Choose from 17 templates for different slide types
+      - Run pnpm run dev to preview with hot reload
+
+  - template: center
+    title: Start Building!
+    text: "Edit presentations/my-first-deck/index.md to add your slides."
+
+  - template: title
+    title: Thank You!
+    subtitle: Questions?
+---

package/scaffold/nvmrc

@@ -0,0 +1 @@
+22

package/scaffold/package.json.tmpl

@@ -0,0 +1,25 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "lazyslides validate && concurrently \"pnpm:watch:*\"",
+    "watch:css": "tailwindcss -i src/styles.css -o _site/assets/css/styles.css --watch",
+    "watch:11ty": "eleventy --serve",
+    "build": "lazyslides validate && pnpm run build:css && pnpm run build:11ty",
+    "build:css": "tailwindcss -i src/styles.css -o _site/assets/css/styles.css",
+    "build:11ty": "eleventy",
+    "validate": "lazyslides validate",
+    "renumber": "lazyslides renumber",
+    "pdf": "lazyslides pdf"
+  },
+  "dependencies": {
+    "lazyslides": "^2.0.0"
+  },
+  "devDependencies": {
+    "@11ty/eleventy": "^3.0.0",
+    "@tailwindcss/cli": "^4.0.0",
+    "concurrently": "^9.0.0",
+    "tailwindcss": "^4.1.18"
+  }
+}

package/scaffold/presentations.11tydata.js

@@ -0,0 +1,11 @@
+export default {
+  layout: "presentation.njk",
+  eleventyComputed: {
+    permalink(data) {
+      if (data.page.filePathStem.endsWith("/index")) {
+        return `/presentations/${data.page.fileSlug}/`;
+      }
+      return false;
+    },
+  },
+};

package/scaffold/styles.css

@@ -0,0 +1,3 @@
+@import "lazyslides/styles.css";
+@source "../presentations/**/*.md";
+/* custom styles below */