d2da71e53a
- Reveal.js presentation on Skills and Subagents pattern - Nix flake with Caddy-based HTTP server and process-compose orchestration - ADRs documenting architectural decisions - Skills for AI implementation guidance - Full Scott Scoble author attribution in README
89 lines
2.8 KiB
Markdown
89 lines
2.8 KiB
Markdown
# 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
|