pavlo-marp-presentation

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: pavlo-marp-presentation
description: >
  Create, edit, preview, and export Marp Markdown presentations via CLI.
  Use when creating or working with slide decks, exporting to PDF,
  or previewing presentations. Installs marp-cli via Homebrew if missing.
metadata:
  author: Pavlo Glushko
  version: "1.3.0"
  applies_to:
    - "docs/**/*presentation*.md"
    - "docs/**/*slides*.md"
  triggers:
    - create presentation
    - create slides
    - marp
    - export to pdf
    - export presentation
    - preview presentation
    - preview slides
    - slide deck
    - mermaid diagram
  capabilities:
    - install marp-cli via Homebrew when not present
    - create new Marp Markdown presentations
    - edit existing Marp presentations
    - export presentations to PDF
    - open a live-reload preview in the browser
    - add and position images, tables, and diagrams in slides
    - render Mermaid diagrams to SVG via mermaid-cli (Homebrew) and embed them in slides
---

# Skill: Marp Presentation

Create, edit, preview, and export Marp Markdown slide decks via the CLI.
PyCharm has no native Marp plugin,
so this skill uses `marp-cli` (installed via Homebrew) for all operations.

## Prerequisites — Ensuring `marp-cli` Is Installed

Run `marp` commands directly.
If a command exits with "command not found" (exit code 127),
install via Homebrew and then re-run the original command:

```bash
brew install marp-cli
```

If Homebrew itself is missing, stop and ask the user to install it first
([https://brew.sh](https://brew.sh)).

## File Location & Naming

- Presentation files live in `docs/` (or a subdirectory of `docs/`).
- Name files descriptively in snake_case:
  `docs/presentation_deep_dive.md`, `docs/slides_m4_review.md`.
- Exported PDFs are written next to the source file by default
  (e.g., `docs/presentation_deep_dive.pdf`).

## Creating a New Presentation

### Front Matter

Every Marp file **must** start with a YAML front-matter block:

```yaml
---
marp: true
theme: default
paginate: true
html: true
style: |
  section {
    font-size: 24px;
  }
---
```

Required fields:

| Field      | Value                              | Purpose                  |
|------------|------------------------------------|--------------------------|
| `marp`     | `true`                             | Enables Marp rendering   |
| `theme`    | `default` or `gaia` or `uncover`   | Visual theme             |
| `paginate` | `true`                             | Shows slide numbers      |
| `html`     | `true`                             | Enables inline HTML — **always include** (see note below) |

> **Why `html: true` is required:**
> Without it, Marp silently strips `style` attributes from all inline HTML
> (e.g. `<span style="color: grey;">`), so coloured or styled text
> renders as plain black text in the exported PDF.

Optional but recommended:

| Field | Value | Purpose |
|-------|-------|---------|
| `header` | any string | Repeated header on every slide |
| `footer` | any string | Repeated footer on every slide |
| `style` | CSS block | Custom styling (font size, colors, etc.) |

### Slide Separators

Use `---` on its own line to separate slides.
The first slide starts immediately after the front-matter closing `---`.

### Slide Structure

```markdown
---
marp: true
theme: default
paginate: true
html: true
---

# Presentation Title

Subtitle or tagline

---

## Section Heading

- Bullet point one
- Bullet point two

---
```

## Marp Syntax Quick Reference

### Images

```markdown
![bg](path/to/image.png)          <!-- full-slide background -->
![bg right:40%](path/to/img.png)  <!-- right 40% background, content on left -->
![bg left:50%](path/to/img.png)   <!-- left 50% background, content on right -->
![w:400](path/to/img.png)         <!-- inline image, 400px wide -->
```

Use relative paths from the Markdown file's directory.
The `--allow-local-files` flag is required for local images during export.

### Speaker Notes

```markdown
<!-- This is