Cline rules

1---
2description: Provides guidelines and best practices for creating and working with Slidev presentation projects.
3author: https://github.com/nickbaumann98
4version: 1.0
5category: "Presentation Tools"
6tags: ["slidev", "slides", "markdown", "vue", "vite", "guide"]
7globs: ["slides.md", "**/slides.md", "*.vue", "layouts/**/*.vue", "components/**/*.vue"]
8---
9# Slidev Project Instructions
10 
11This document provides guidelines for working with Slidev projects. Slidev is a Markdown-based presentation tool powered by Vue and Vite.
12 
13## Core Concepts & Structure
14 
151. **Entry Point**: The main presentation content is typically in `http://slides.md`.
162. **Slide Separation**: Slides are separated by `---` on a new line.
173. **Frontmatter/Headmatter**:
18* YAML blocks at the beginning of the file (`--- ... ---`) configure the deck (headmatter) or individual slides (frontmatter).
19* Headmatter (first block) applies globally (e.g., `theme`, `title`, `addons`).
20* Frontmatter configures specific slides (e.g., `layout`, `background`, `class`, `transition`, `clicks`).
21* **YAML Quoting:** Prefer double quotes (`"..."`) for strings containing single quotes (`'`) to avoid parsing errors (e.g., `title: "My Deck's Title"`).
224. **Layouts**:
23* Define the structure of slides. Specified via `layout:` in frontmatter.
24* Default layout for the first slide is `cover`, others are `default`.
25* Custom layouts are placed in the `layouts/` directory as `.vue` files. Use `<slot />` for default content and named slots (`<slot name="xxx" />`) for specific sections.
265. **Components**:
27* Vue components can be used directly in Markdown (e.g., `<MyComponent />`).
28* Components are auto-imported from:
29* Slidev built-ins (`@slidev/client/builtin/`).
30* The active theme.
31* Installed addons.
32* The local `components/` directory.
33* Custom components go in the `components/` directory as `.vue` files.
346. **Styles**:
35* [UnoCSS](https://unocss.dev) is built-in for utility-first styling. Apply classes directly in Markdown or components.
36* Global styles can be added in the `styles/` directory (e.g., `styles/index.css`).
37* Scoped styles for a specific slide can be added using `<style scoped>...</style>` within the slide's Markdown.
387. **Assets**:
39* Static assets (images, videos) can be placed in the `public/` directory and referenced with absolute paths starting with `/` (e.g., `background: /my-image.png`).
40* Relative paths (e.g., `./image.png`) work for standard Markdown image syntax (`![alt](./image.png)`) but might break in frontmatter or components after building. Prefer the `public/` directory method for reliability.
418. **Notes**:
42* Presenter notes are added as HTML comments (`<!-- ... -->`) at the *very end* of a slide's Markdown content.
43* Notes support Markdown formatting.
44 
45## Key Features & Syntax
46 
471. **Code Blocks**:
48* Use standard Markdown fenced code blocks (e.g., ` ```ts ... ``` `).
49* Syntax highlighting is provided by Shiki.
50* Supports line highlighting (`{1,3-5}`), line numbers (`{lines:true}`), Monaco editor (`{monaco}`), diffs (`{monaco-diff}`), code imports (`<<< @/path/to/file.js#region {lines=...}`). Refer to the Syntax Guide for details.
512. **Animations (Clicks)**:
52* Use `<v-click>` component or `v-click` directive to reveal elements step-by-step.
53* `v-after` reveals elements simultaneously with the previous `v-click`.
54* `.hide` modifier (e.g., `v-click.hide`) hides elements instead of showing them.
55* `<v-clicks>` component applies `v-click` to its children (useful for lists).
56* Control timing with `at="..."` (e.g., `v-click="3"` for absolute click 3, `v-click="'+2'"` for 2 clicks after the previous relative element).
57* Specify enter/leave ranges: `v-click="[2, 5]"` (visible from click 2 up to, but not including, 5).
58* Override total clicks per slide with `clicks: N` in frontmatter.
593. **Motion (VueUse Motion)**:
60* Use the `v-motion` directive for element transitions (e.g., `:initial="{ x: -80 }" :enter="{ x: 0 }"`).
61* Can be triggered by clicks using `:click-N` attributes (e.g., `:click-1="{ y: 30 }"`).
624. **Slide Transitions**:
63* Set in headmatter (`transition: slide-left`) for global effect or frontmatter for specific slides.
64* Built-in transitions: `fade`, `fade-out`, `slide-left`, `slide-right`, `slide-up`, `slide-down`, `view-transition`.
65* Specify different forward/backward transitions: `transition: slide-left | slide-right`.
665. **Diagrams**: Supports Mermaid (` ```mermaid ... ``` `) and PlantUML (` ```plantuml ... ``` `).
676. **LaTeX**: Use `$` for inline math (`$a^2+b^2=c^2$`) and `$$` for block math.
687. **Global Context**: Access runtime info like `$nav` (navigation controls), `$clicks` (current click count), `$page` (current slide number), `$frontmatter`, `$slidev.configs` within components or directly in Markdown using `{{ }}`. Use composables like `useNav()` from `@slidev/client` in `<script setup>`.
69 
70## Development Workflow
71 
721. **Initialization (Full Project)**: Use `pnpm create slidev <project-name>` (or npm/yarn/bun equivalent).
732. **Development Server (Full Project)**: Run `pnpm dev` (or `npm run dev`, etc.) in the project directory. Access at `http://localhost:3030`.
743. **Development Server (Single File)**: Navigate to the directory containing your `slides.md` and run `npx @slidev/cli`. This is useful for quick previews without a full project setup.
75    * **Note:** Ensure you use the correct package name: `@slidev/cli`.
76    * **Theme Installation:** If a theme specified in the frontmatter (e.g., `theme: seriph`) isn't installed, Slidev will prompt you to install it. Confirm by pressing 'y' and choosing your package manager (e.g., 'npm').
774. **Editing**: Modify `slides.md` and add custom components/layouts/styles as needed.
784. **Exporting**:
79* Install `playwright-chromium` (`pnpm add -D playwright-chromium`).
80* Run `pnpm export` (or `npm run export`, etc.) to generate a PDF (`slides-export.pdf` by default).
81* Use `--format png` or `--format pptx`.
82* Use `--with-clicks` to export each click step as a separate page/image.
83* Use `--output <filename>` to specify the output file.
84* Use `--dark` for dark mode export.
855. **Building for Hosting**:
86* Run `pnpm build` (or `npm run build`, etc.) to create a static SPA in the `dist/` folder.
87* Use `--base /path/` if deploying to a subpath.
88* Deploy the `dist` folder to static hosting (Netlify, Vercel, GitHub Pages). Configuration files (`netlify.toml`, `vercel.json`, GitHub Actions workflow) are often included in the starter template.
89 
90## Best Practices
91 
92* Keep `http://slides.md` focused on content.
93* Use layouts for consistent slide structure.
94* Use components for reusable UI elements and interactivity.
95* Leverage themes and addons for styling and features before building custom solutions.
96* Use the `public/` directory for static assets referenced in frontmatter or components.
97* Utilize presenter mode (`/presenter` route or button) for notes and controls during presentation.
98* Pay attention to terminal output for errors (e.g., YAML parsing issues) when starting the server.
99