beyond-the-prompt/docs/adr/001-presentation-technology.md

ADR 001: Presentation Technology Choice

Status

Proposed

Context

We need to create a presentation for "Beyond the Prompt: Lessons from Building with Claude Code" that:

• Can be served via simple HTTP server
• Works well with Nix flake distribution
• Supports code syntax highlighting
• Allows for presenter notes
• Is version-controllable (text-based)
• Can be easily edited and previewed

Decision

Use Reveal.js for the presentation framework.

Rationale

Reveal.js Advantages

• Static HTML/JS/CSS: Can be served with any simple HTTP server
• Rich features: Code highlighting, presenter notes, speaker view, PDF export
• Nix-friendly: Available via nixpkgs, no complex build process
• Offline-capable: All assets can be bundled
• Markdown support: Can write slides in Markdown within HTML
• Wide adoption: Well-documented, stable, extensive plugin ecosystem

Alternatives Considered

Marp

• Pros: Pure Markdown, simpler syntax
• Cons: Requires CLI tool, more complex Nix integration, fewer interactive features
• Verdict: Too limiting for technical demos

Slidev

• Pros: Vue-based, modern developer experience
• Cons: Requires Node.js build process, heavier Nix integration
• Verdict: Unnecessary complexity for this use case

Beamer/LaTeX

• Pros: Academic standard, precise control
• Cons: PDF-only, no interactive demos, steep learning curve
• Verdict: Not suitable for live coding demonstrations

Implementation Details

Directory Structure

presentation/
├── index.html          # Main presentation file
├── css/
│   └── theme/         # Custom themes if needed
├── js/
│   └── reveal.js      # Vendored or symlinked
└── assets/
    ├── images/
    └── code-samples/

Serving

• Development: nix run .#present → lightweight HTTP server from nixpkgs (e.g., darkhttpd, caddy, or miniserve)
• Production: Static hosting (GitHub Pages, Netlify, etc.)

Reveal.js Integration in Nix

Use nixpkgs to fetch reveal.js dependencies:

• Option 1: fetchFromGitHub to get reveal.js source
• Option 2: Use buildNpmPackage if npm-based tooling needed
• Option 3: Direct vendoring with fetchurl for specific release

Recommended: fetchFromGitHub for reproducibility and ease of updates.

Consequences

Positive

• Simple development workflow
• No build step required for basic presentations
• Easy to version control
• Works offline
• Familiar to many developers

Negative

• Manual Reveal.js updates (if vendored)
• Larger repo size if vendoring full Reveal.js
• Less separation between content and presentation (vs. pure Markdown)

Mitigation

• Keep Reveal.js minimal (only required files)
• Use Markdown mode for slide content where possible
• Document update process for Reveal.js version bumps