Slidev Presentation Skill — bears-ppt-skill

A self-contained guide for any AI assistant or new contributor to immediately start authoring an academic paper-share Slidev deck without prior context. Read this once, then begin working on the target project's slides.md.

This skill was distilled from a real paper-share project. Its rules trace to concrete bugs and revisions, not theoretical best practices.

1. What This Skill Is For

Building a Slidev presentation deck — a Vue-based framework that turns a single Markdown file into an interactive slide show — for academic paper-share use cases. The original deck on which this skill was authored shared:

> A Novel RFID Authentication Protocol Based on a Block-Order-Modulus Variable Matrix Encryption Algorithm (IEEE TIFS, 2025)

The tone is academic, not promotional. See §6.

The skill applies generally to any "convert an academic paper into a 30-slide deck" task.

2. Expected Project Layout

This skill assumes a Slidev project with the following structure (paths used in scripts default to this layout):

your-slidev-project/
├── slides.md                                            ← ★ MAIN EDIT TARGET ★
├── pdf_text.txt                                         ← page-delimited PDF text (produced by extract_pdf.py)
├── components/                                          ← auto-imported Vue components
│   ├── *.vue
├── scripts/                                             ← batch helpers from this skill
│   ├── extract_pdf.py
│   ├── fix_math.py
│   ├── fix_headings.py
│   ├── fix_tables.py
│   ├── fix_anim_loop.py
│   ├── normalize_spacing.py
│   ├── academic_tone.py
│   └── replace_block.py
├── public/                                              ← static assets, e.g. /xdu.jpg
└── package.json

The deck being edited is slides.md at the project root. Scripts default to operating on ../slides.md relative to the scripts/ folder.

3. Common Commands

Run from inside the project root:

npm install                           # first-time setup
npm run dev                           # dev server at http://localhost:3030 with HMR
npm run build                         # static build
npm run export                        # PDF
npx slidev export --format pptx       # PPTX

If the dev server reports Port 3030 is already in use:

lsof -ti:3030 | xargs kill -9

4. Editing Workflow

1. Read slides.md before editing. Use line-anchored Edit calls; never blindly rewrite. Slides are separated by --- lines, so you can locate a slide by its index (1-based, counting frontmatter as page 1).
2. Rely on HMR. After editing slides.md or any components/.vue, do not* restart Vite. HMR handles markdown, Vue SFC, and CSS changes cleanly. Only kill/restart on explicit user request or port conflict.
3. Keep edits minimal and surgical. Don't refactor untouched slides. Don't reformat unrelated markup.
4. Verify visually. When the change is significant, suggest the user reload localhost:3030 and navigate to the affected pages. For text-only changes, no verification needed.
5. For tone-related rewrites, after editing run python scripts/academic_tone.py (or the equivalent grep):

```

Grep pattern="恐怖|魔术|破局|无懈可击|完美|彻底|金贵|致命|惊人|爆炸|洗牌|掠影|！" path=slides.md

```

No matches expected.

5. Slidev Authoring Conventions (HARD RULES)

These rules were learned from real bugs. Violating them produces broken output.

5.1 Math inside HTML — never use KaTeX $…$ inside HTML tags

KaTeX $p$ / $$ … $$ does not render when nested inside

,

<span class="matrix">
  <span>a</span><span>b</span>
  <span>c</span><span>d</span>
</span>

<style scoped>
.matrix {
  display: inline-grid;
  grid-template-columns: repeat(2, 1.4em);
  grid-auto-rows: 1.4em;
  align-items: center;
  justify-items: center;
  padding: 0 0.5em;
  border-left: 2px solid currentColor;
  border-right: 2px solid currentColor;
  font-style: italic;
  font-size: 1.1em;
}
</style>

<div class="font-mono p-grid">
  <span>P<sub>1</sub> = (a+d)(e+h)</span>
  <span>P<sub>2</sub> = (c+d) · e</span>
  <span>P<sub>3</sub> = a · (f−h)</span>
  <span>P<sub>4</sub> = d · (g−e)</span>
  ...
</div>

<style scoped>
.p-grid {
  display: grid;
  grid-template-columns: repeat(2, 1fr);
  gap: 2px 12px;
}
</style>

<div class="mt-6 text-sm max-h-[300px] overflow-y-auto pr-2 transform scale-90 origin-top">

<table>
  <tbody>
    <tr><td>…</td></tr>
  </tbody>
</table>

let timerId = null
const playStep = () => {
  if (activeStep.value < steps.length - 1) {
    timerId = setTimeout(() => { activeStep.value++; playStep() }, 2000)
  } else { /* end state */ }
}
onUnmounted(() => clearTimeout(timerId))

---
theme: seriph
background: /xdu.jpg
class: 'text-center'
lineNumbers: false
transition: fade-out
css: unocss
---

---
layout: center
class: text-center
---