opencoven/coven/slidev-deck-pipeline

Slidev Deck Pipeline

The single, repeatable path for turning content into a published OpenCoven Slidev deck. Optimize for determinism: same inputs → same deck → same verified dist → same deploy. Author by writing a real .md file with Node's fs.writeFileSync, then run the repo's own scripts to verify and build. Never eyeball-ship.

When to use

Repo facts (canonical)

• Repo: /Users/buns/Documents/GitHub/OpenCoven/open-coven-weekly
• Decks: slides/YYYY-MM-DD.md (a -slug suffix is allowed: YYYY-MM-DD-slug.md)
• Template: slides/template.md
• Theme: theme/ = @opencoven/slidev-theme-coven; referenced from a deck as theme: ../theme
• Static assets: slides/public/ → served at / (images live in slides/public/img/, referenced as /img/<name>)
• Package manager: pnpm
• Deploy: Vercel project open-coven-weekly, aliased to show.opencoven.ai, auto-deploys on push to main

The scripts (this is the deterministic core — always use them)

Deck resolution is automatic and deterministic (scripts/deck-utils.mjs): the latest deck is the one with the highest YYYY-MM-DD; on a date tie, the shorter filename wins (so a bare 2026-07-15.md beats a slugged 2026-07-15-draft.md). To make a deck "the live one," give it the latest date and the shortest name.

The deterministic loop (follow in order)

1. Gather content — merged PRs (gh pr list --state merged --limit 30), releases

(gh release list), and any Sage brief. Cluster into topics (one topic ≈ one slide).

1. Scaffold — pnpm new (or copy the newest deck as a starting idiom for a slugged one-off).
2. Author the file with Node `fs.writeFileSync` — NOT shell heredocs/echo (they truncate long

content and mangle escapes). See references/authoring.md.

1. Verify — pnpm verify (or at minimum node scripts/verify-week.mjs). Fix every failure.

The verifier enforces: no blank slides, a speaker note on every slide, required strings (theme: ../theme, layout: cover, layout: default, discord.gg/opencoven), a frontmatter title:, and the deck's date present in the body.

1. Preview — pnpm dev, spot-check every slide and every image renders in-browser.
2. Commit & push — git add slides/YYYY-MM-DD.md slides/public/img/<new> then

git commit -m "slides: add YYYY-MM-DD Show'n Spells deck" and git push origin main. Vercel auto-deploys. Commit directly to main for weekly decks.

1. Confirm live — curl the production URL, assert HTTP 200 on index and every referenced image.

House slide idiom (match it exactly)

Non-cover slide skeleton:

---
layout: default
---
 
<div class="label">Section Label</div>
 
# Title with one *italic* word
 
<!-- Full presenter sentences, natural spoken tone.
Use <span class="cue">[stage direction]</span> for cues. -->

• Cover: either layout: cover with a .sub line (Show'n Spells · <time> · discord.gg/opencoven),

or layout: full for an absolute-positioned full-bleed hero (see references/full-bleed-hero.md).

• Theme classes: .label (section kicker), .card + .card-title (grid cards),

.badge-shipped (green, live/merged), .badge-wip (amber, in progress), .cue (speaker-note stage direction).

• Reveals: v-click on cards/list items for progressive reveal.
• Every slide MUST have a `<!-- ... -->` speaker note. No exceptions — the verifier rejects blanks.
• Arc: Cover → Agenda ("Tonight's Spells") → Shipped (one per cluster) → Live demo stop →

Open-floor stops (2–3, scattered) → optional Architecture → Outro (Discord CTA + next-week teaser).

Hard rules (learned the hard way — see references/gotchas.md)

• Author with `fs.writeFileSync`, never heredoc/echo for deck bodies.
• Images: put files in slides/public/img/, reference as /img/<name>.jpg. Full URLs must be

https://. In-browser (pnpm dev / the live Vercel build) renders all images fine.

• PDF export drops early background images (Slidev export-timing bug): it reliably renders only

the last image slides. For a perfect PDF, present from the live URL, or composite the PDF from high-res text-slide renders + the JPEGs at their exact page positions. Do NOT claim a clean PDF without opening it page-by-page.

• Deploy target: reuse the existing open-coven-weekly Vercel project. Do NOT spawn throwaway

projects (dist, coven-threads-explainer, etc.). If you accidentally do, delete them.

• "Standard format" means the house idiom above — theme ../theme, .label/.card, v-click,

speaker notes, the standard arc. When Val says "rebuild the standard way," this is what she means.

References

• references/authoring.md — the Node fs.writeFileSync authoring pattern + template vars
• references/full-bleed-hero.md — the absolute full-bleed image hero recipe (from the Cave party deck)
• references/verify-deploy.md — the exact verify → commit → deploy → confirm-live commands
• references/gotchas.md — PDF export bug, image auth, throwaway-project trap, heredoc trap