# Quizzman Slide Studio — Markdown Format Specification

> Version: 3.0 · Canonical URL: https://app.quizzman.com/slide-studio/docs/markdown-spec.md  
> For AI agents: also see https://app.quizzman.com/slide-studio/llms.txt

Quizzman Slide Studio ingests **Markdown + YAML frontmatter** and renders slides for export to **PPTX, PNG, and MP4** (with optional AI voice).

## Quick start

1. Open https://app.quizzman.com/slide-studio/
2. Create a project or paste Markdown into the editor
3. Set `theme`, `ratio`, and `language` in frontmatter
4. Separate slides with `---` on its own line

## Document structure

```markdown
---
project: "Lesson title"
theme: "hsk-classroom"
ratio: "16:9"
language: "vi"
export:
  image: true
  pptx: true
  video: true
voice:
  enabled: true
  mode: slide
  style: "clear, natural teacher tone"
---

# Slide 1: Cover
::layout cover
::duration 5
## Main title
### Subtitle
:::voice
Opening narration (not shown on slide).
:::

---

# Slide 2: Main idea
::layout content
::duration 8
## Section title
- Point one
- Point two
:::voice
Expanded explanation for video/audio.
:::
```

## Frontmatter fields

| Field | Type | Description |
|-------|------|-------------|
| `project` | string | Project / deck title |
| `theme` | string | Theme id (see Themes) |
| `ratio` | string | `16:9`, `9:16`, `4:3` |
| `language` | string | `vi`, `en`, `zh` |
| `export.image` | bool | Enable PNG export |
| `export.pptx` | bool | Enable PowerPoint export |
| `export.video` | bool | Enable MP4 export |
| `voice.enabled` | bool | Enable AI narration |
| `voice.mode` | string | `slide` (per-slide voice) |
| `voice.style` | string | Tone hint for TTS |
| `live-present` | bool | Enable Slide Present Live (audience: play.quizzman.com/slide) |
| `quiz-placement` | string | `interleaved` (quiz between content) or `end-block` (quiz at end) |
| `quiz-timer` | number | Default quiz timer in seconds |

## Slide separators

- Use `---` alone on a line between slides
- Do **not** wrap the document in ` ```markdown ` fences when pasting into Slide Studio

## Headings (critical)

| Syntax | Purpose |
|--------|---------|
| `# Slide N: Label` | **Internal label only** — not rendered on canvas. Keep short: "Cover", "Main idea", "Example" |
| `## …` | **Visible main title** on the slide |
| `### …` | **Visible subtitle** (optional, common on cover) |
| `- bullet` | Body content (3–5 bullets max, keep short) |

Never put the full lesson title in the `# Slide N:` line.

## Per-slide directives

| Directive | Example | Meaning |
|-----------|---------|---------|
| Layout | `::layout cover` | cover, content, example, two-columns, comparison, quote, image-right, title-body |
| Duration | `::duration 8` | Seconds (for video timeline), not milliseconds |
| Pinyin | `::pinyin nǐ hǎo` | Chinese pronunciation helper |
| Chinese | `::chinese 你好` | Han character emphasis |
| Translation | `::translation Hello` | Gloss / translation |

### Slide Quiz Live (interactive present)

Audience joins at **https://play.quizzman.com/slide** with the session code shown on the host slide.

| Directive | Example | Meaning |
|-----------|---------|---------|
| Quiz slide | `::slide-quiz` | Marks slide as live quiz (canonical Question schema) |
| Choice | `::choice A. Option text` | MCQ option (id + label) |
| Correct | `::correct A` | Correct option id |
| Timer | `::timer 30` | Quiz timer in seconds (host can end early) |
| Viz template | `::viz-template bar-chart` | Reveal/scoreboard skin: `classic-reveal`, `bar-chart`, `podium-top5` |
| Question (static) | `::question …` | Q&A reveal slide (non-live) |
| Answer (static) | `::answer …` | Answer text for Q&A layout |

Example quiz slide:

```markdown
# Slide 4: Quick check
::layout quiz-question
::slide-quiz
::timer 30
::viz-template bar-chart

## What is the correct usage of 正好?

::choice A. Size fits exactly
::choice B. By coincidence
::choice C. Same as 刚好
::correct A

:::voice
Open play.quizzman.com/slide and enter the code on screen.
:::
```

Questions compile to `quizDocument` (compatible with Quiz Engine export).

## Fenced blocks

```markdown
:::voice
Narration script for AI voice / video. Can be longer than on-slide text.
:::

:::note
Speaker notes — not shown on slide or in export preview.
:::
```

## Themes (`theme:` in frontmatter)

Common ids:

- `bright-scholar` — academic, clear
- `hsk-classroom` — HSK / classroom Vietnamese + Chinese
- `qz-grammar-pro` — grammar lessons
- `chinese-classic` — classical Chinese aesthetic
- `dark-tech` — modern dark
- `minimal-white` — minimal light

## Layout guide

- **cover** — opening slide (title + subtitle)
- **content** / **title-body** — title + bullet list
- **example** — example / case study (same structure as content)
- **two-columns** — split content
- **comparison** — side-by-side contrast
- **quote** — quotation highlight
- **image-right** — text + image slot

## Content rules (for AI-generated decks)

1. Do not invent facts beyond the source document
2. One main idea per slide; max 3–5 short bullets
3. Long explanations go in `:::voice`, not on the slide
4. Missing data → mark `[CẦN BỔ SUNG]` / `[NEEDS INPUT]`, do not fabricate
5. Preserve Chinese characters, pinyin, and glosses when present
6. Voice must sound natural — not a verbatim bullet readout
7. Output plain Markdown matching this spec

## Export pipeline

Markdown → Slide Studio parser → slide document v3 → render → **PPTX / PNG / MP4**

## Links

- Editor: https://app.quizzman.com/slide-studio/
- About: https://app.quizzman.com/slide-studio/about
- llms.txt: https://app.quizzman.com/slide-studio/llms.txt
- Example deck: https://app.quizzman.com/slide-studio/docs/example-deck.md

## Full example

See `example-deck.md` in this directory.