| name | slidev-deck-pipeline |
| description | Deterministic pipeline for authoring, verifying, exporting, and deploying OpenCoven Slidev decks (the weekly Show'n Spells system and one-off branded decks). Use whenever asked to build, rebuild, update, export, or publish a Slidev slide deck for OpenCoven — weekly meeting decks, launch decks, or explainer decks. |
| version | 1.0.0 |
| author | Charm |
| license | AGPL-3.0-only |
| tags | ["Slidev","slides","deck","show-n-spells","open-coven-weekly","presentation","vercel","deterministic"] |
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
| Scenario | Use this skill |
|---|
| Weekly Open Coven / Show'n Spells deck | ✅ (the canonical path) |
| One-off launch / explainer deck in the same house style | ✅ |
| Rebuilding an existing deck "the standard way" | ✅ |
| Exporting a deck to PDF | ✅ |
Deploying a deck to Vercel (show.opencoven.ai) | ✅ |
| Non-Slidev copy (tweets, Discord posts) | ❌ use the voice/social skills instead |
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)
| Command | What it does |
|---|
pnpm new (node scripts/new-week.mjs) | Scaffolds next Sunday's slides/YYYY-MM-DD.md from template.md, replacing {{DATE}} and {{MONTH_DAY_YEAR}} |
pnpm dev | Live Slidev preview of the latest dated deck (auto-resolved) |
pnpm build | Build with GitHub-Pages base /open-coven-weekly/ |
pnpm build:vercel | Build with root base / → publishes slides/dist (this is what Vercel runs) |
pnpm export | Installs Chromium, exports the latest deck to PDF |
pnpm verify | pnpm test + verify-week + both builds + verify:dist — the full gate |
pnpm verify:dist | Confirms built dist/index.html contains the latest deck's frontmatter title |
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)
- 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).
- Scaffold —
pnpm new (or copy the newest deck as a starting idiom for a slugged one-off).
- Author the file with Node
fs.writeFileSync — NOT shell heredocs/echo (they truncate long
content and mangle escapes). See references/authoring.md.
- 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.
- Preview —
pnpm dev, spot-check every slide and every image renders in-browser.
- 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.
- 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 varsreferences/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 commandsreferences/gotchas.md — PDF export bug, image auth, throwaway-project trap, heredoc trap
