Slidev Deck
Procedural runbook, reusable Vue components/layouts, and server tooling for building high-signal technical slide decks with Slidev (slides/), embedded asciinema-player terminal recordings, dark-mode typography, and static GitHub Pages deployment.
Works alongside /asciinema (recording, sanitizing, and trimming .cast files), /ios-simulator-screenshot (staging and verifying mobile simulator screen captures under artifacts/screenshots/<project_name>/), and /crop-image (trimming transparent margins and solid borders on slide images).
Workflows
Choose the matching workflow based on your objective:
- Scaffold a New Slidev Deck
- Structure Modular Acts
- Author Slides, Layouts & Presenter Notes
- Embed Terminal Recordings & Visual Assets
- Run & Manage the Local Dev Server
- Verify Build & Deploy to GitHub Pages
1. Scaffold a New Slidev Deck
Initialize a new slides/ workspace from the bundled templates in resources/:
- Create the directory hierarchy and copy the starter configuration, theme stylesheet, component, and custom layouts:
mkdir -p slides/{acts,components,layouts,public/casts,public/images} cp .agents/skills/slidev-deck/resources/package.json slides/package.json cp .agents/skills/slidev-deck/resources/vite.config.ts slides/vite.config.ts cp .agents/skills/slidev-deck/resources/style.css slides/style.css cp .agents/skills/slidev-deck/resources/slides.md slides/slides.md cp .agents/skills/slidev-deck/resources/acts/01-primer.md slides/acts/01-primer.md cp .agents/skills/slidev-deck/resources/components/AsciinemaPlayer.vue slides/components/AsciinemaPlayer.vue cp .agents/skills/slidev-deck/resources/layouts/*.vue slides/layouts/ - Update the
--base /<repo-name>/flag inslides/package.json("build": "slidev build --base /<repo-name>/") to match the repository name for GitHub Pages subpath hosting (or omit--baseif deploying to a custom root domain). - Add
slides/node_modules/,slides/dist/,slides/.slidev.pid, andslides/.slidev.logto.gitignore. - Install dependencies:
npm --prefix slides install - Completion Criterion:
slides/node_modules/is populated andnpm --prefix slides run buildexits with code 0.
2. Structure Modular Acts
Split multi-part presentations into Act-level markdown files under slides/acts/ while keeping slides/slides.md as the master manifest:
- Configure
slides/slides.mdwith global presentation headmatter (colorSchema: dark,background: '#121317',highlighter: shiki,mdc: true) and sethide: trueon the headmatter block so Slidev does not insert a blank initial slide or leak headmatter fields into the first act:--- theme: default background: '#121317' colorSchema: dark highlighter: shiki lineNumbers: false info: | ## Presentation Title Subtitle and Presenter Info drawings: persist: false transition: slide-left title: Presentation Title mdc: true hide: true --- --- src: ./acts/01-primer.md --- --- src: ./acts/02-core-story.md --- - Name act files sequentially (
01-primer.md,02-the-hook.md, etc.) insideslides/acts/. - Tag every slide with a unique comment identifier immediately after its frontmatter block (e.g.,
<!-- S01 -->,<!-- S12 -->) to anchor edits and reviews. - Completion Criterion:
slides/slides.mdcontainshide: truein its headmatter block and everysrc: ./acts/...entry resolves to a valid markdown file inslides/acts/.
3. Author Slides, Layouts & Presenter Notes
Follow the slide design conventions below. For copy-pasteable HTML/Markdown templates of every slide archetype, read references/SLIDE-PATTERNS.md.
Core Formatting Conventions:
- Clean Slide Headings: Render slide titles using a clean flex header container without badges, pills, or Act chips:
<div class="flex items-center gap-3 mb-6"> <h2 class="text-2xl font-bold m-0">Slide Title</h2> </div> - Numbered Concept Lists: Present multi-point explanations and comparisons as structured numbered lists (
<ol>) with bold white titles and nested<ul>takeaways rather than cramped multi-card grids or dense multi-column tables:
When comparing 3–4 broad paradigms (e.g., MCP vs. Rules vs. Skills), give each concept its own focused numbered-list slide followed by a synthesis slide rather than squeezing all columns into one tiny table.<ol class="space-y-4 text-sm text-gray-200 list-decimal pl-6 mt-5 leading-relaxed"> <li> <strong class="text-white">Topic / Feature Title</strong> <ul class="list-disc pl-5 mt-1 space-y-1 text-gray-300"> <li>Primary high-signal takeaway or mechanism</li> <li>Secondary context or contrast</li> </ul> </li> </ol> - Flush Code Fences Inside HTML: Place markdown fenced code blocks (
```) flush at column 0 with blank lines above and below whenever they sit inside HTML<div>wrappers. Indenting a fenced code block by 4+ spaces inside HTML causes Markdown to render raw tags instead of highlighted code. - Conversational Presenter Notes: Conclude every slide with an HTML comment (
<!-- ... -->) containing natural spoken narrative that explains the transition and talking points behind each bullet. Write pure spoken prose without bracketed stage directions ([Click],[Next slide]).
Choosing a Slide Layout:
layout: center(class: text-center): Title slide, Act divider slides, and big-quote callouts.layout: default: Concept lists, 2-column anti-pattern vs. solution cards (bg-red-950/15vs.bg-emerald-950/15), and code/architecture tables.layout: cast-full: Full-viewport interactiveasciinema-playerslide (title,cast: /casts/file.cast,autoPlay: false,speed: 2.0,idleTimeLimit: 2.0,fit: both, and optionalshowChapterBar: trueduring development).layout: skill-breakdown: Framed zoom-in card (way: 1|2|3|mashup,title).layout: hardware-callout: 12-column split pairing a framed image and optional caption overlay on the left (title,image: /images/file.png,imageCaption) with explanatory HTML content in the default slot on the right.
Completion Criterion: Every authored slide includes a clean <h2> header (or uses a dedicated layout header), unindented code fences with blank line separators, and a conversational <!-- ... --> speaker note block.
4. Embed Terminal Recordings & Visual Assets
Consult references/ASCIINEMA-INTEGRATION.md for component props, Vite SSR rules, and base-path normalization details.
- Prepare & Embed
.castRecordings:- Before executing a multi-cast Recording Run, use /asciinema (
.agents/skills/asciinema/references/RUNBOOK-FORMAT.md) to generate an operatorRUNSHEET.mdfromTODO.mdor the slide blueprint (separatingrecordings/raw/fromrecordings/final/at120x36with paired Before / After"m"stop points). - Treat
recordings/final/<name>.castas the single source of truth. Use /asciinema to sanitize secrets (sanitize-cast.py), strip trailing shell exit prompts (trim-cast.py --in-place), and place/verify"m"chapter stop points (mark-cast.py --list/--set) on the canonical recording inrecordings/final/, then runnpm --prefix slides run sync-casts(also executed automatically bypredevandprebuild) to syncrecordings/final/*.castintoslides/public/casts/. - For shell commands and TUI launchers in
zsh(e.g.flutter create ...,git init && ...,agy), place command-entry stop points on the typed/pasted command text rather than post-launch banners;mark-cast.pyautomatically advances past bracketed-paste reverse video ([REV]) to the un-reversed redraw ([UNREV]) and splits trailing\x1b[1B\r\x1b[Kcursor-down sequences into a post-marker"o"event (dt=0.02s) so the cursor stays on the same line at the end of the command. - Reference recordings with root-relative paths in slide frontmatter:
--- layout: cast-full title: "Recording Title" cast: /casts/demo.cast autoPlay: false speed: 2.0 idleTimeLimit: 2.0 fit: both --- AsciinemaPlayer.vuecompiles each breakpoint-bounded segment to run at>= speed(default2.0x) and complete in<= maxSegmentDuration(default30s). By default in final presentation slides (showChapterBar: false), it renders a clean minimalistPlayback speed: Nxbadge beneath the terminal while supporting[/]/pstage hotkeys; setshowChapterBar: truein slide frontmatter during development to display interactive chapter stepper pills, transport controls, and segment metadata.
- Before executing a multi-cast Recording Run, use /asciinema (
- Prepare & Embed Images:
- For mobile app runs, use
/ios-simulator-screenshot(xcrun simctl io booted screenshot /abs/path/to/repo/artifacts/screenshots/<project_name>/<file>.pngwith full absolute paths) to stage clean device-framebuffer screenshots per run inartifacts/screenshots/<project_name>/. - Use /crop-image (
crop.py --inspect/--autocrop) to verify dimensions or remove excess transparent margins/solid borders before copying presentation-ready images intoslides/public/images/. - Reference images via
image: /images/<filename>inhardware-calloutslides.
- For mobile app runs, use
- Preserve
BASE_URLResolution in Custom Vue Files:- In any custom Vue layout or component that loads local assets from
slides/public/, normalize paths withimport.meta.env.BASE_URLso assets resolve on both local dev (/) and GitHub Pages subpaths (/<repo-name>/).
- In any custom Vue layout or component that loads local assets from
- Completion Criterion: All
/casts/*and/images/*paths referenced inslides/acts/*.mdexist inslides/public/{casts,images}/.
5. Run & Manage the Local Dev Server
Manage the background Slidev development server using the bundled scripts/slides-server.sh utility:
# Start server on default port 3030 (auto-installs node_modules if missing)
.agents/skills/slidev-deck/scripts/slides-server.sh start
# Check server PID, HTTP status, and navigation URLs
.agents/skills/slidev-deck/scripts/slides-server.sh status
# Restart or stop the server
.agents/skills/slidev-deck/scripts/slides-server.sh restart
.agents/skills/slidev-deck/scripts/slides-server.sh stop
# Use a custom port if 3030 is in use
.agents/skills/slidev-deck/scripts/slides-server.sh start -p 3040Live Slidev Endpoints:
- Presentation Deck:
http://localhost:3030/ - Presenter Console (speaker notes, timer, next slide):
http://localhost:3030/presenter - Slide Overview Grid:
http://localhost:3030/overview
Completion Criterion: Running .agents/skills/slidev-deck/scripts/slides-server.sh status reports RUNNING with HTTP: 200 (or 304).
6. Verify Build & Deploy to GitHub Pages
- Run the static production build to verify that all Vue components, layouts, Shiki code blocks, and Markdown slides compile cleanly:
npm --prefix slides run build - To configure automated GitHub Pages deployment, copy the workflow template into
.github/workflows/deploy-slides.yml:
Ensuremkdir -p .github/workflows cp .agents/skills/slidev-deck/resources/deploy-slides.yml .github/workflows/deploy-slides.ymlon.push.pathsin.github/workflows/deploy-slides.ymlincludes every upstream directory synced byprebuild(e.g.,'slides/**','recordings/final/**', and any external tutorial or asset folders) so pushing changes to those files triggers the GitHub Pages workflow. - Ensure repository GitHub Pages settings are configured with Build and deployment > Source: GitHub Actions.
- Completion Criterion:
npm --prefix slides run buildexits with returncode 0 and generatesslides/dist/index.html.