Markdown Format Specification

Quizzman Slide Studio v3 · For AI agents & developers · markdown-spec.md

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

Quick start

1. Open Slide Studio
2. Create a project or paste Markdown
3. Set theme, ratio, language in frontmatter
4. Separate slides with --- on its own line

Document structure

---
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.*	bool	image, pptx, video
voice.*	mixed	enabled, mode, style
live-present	bool	Enable Slide Present Live (audience: play.quizzman.com/slide)
quiz-placement	string	interleaved or end-block
quiz-timer	number	Default quiz timer in seconds

Headings (critical)

Syntax	Purpose
# Slide N: Label	Internal only — not on canvas. Short label: Cover, Main idea
## …	Visible main title
### …	Visible subtitle
- bullet	Body (3–5 bullets max)

Per-slide directives

• ::layout cover|content|example|two-columns|comparison|quote|image-right|title-body|quiz-question
• ::duration N — seconds (not ms)
• ::pinyin, ::chinese, ::translation — Chinese helpers

Slide Quiz Live (interactive present)

Audience joins at 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
Viz template	::viz-template bar-chart	classic-reveal, bar-chart, podium-top5
Question (static)	::question …	Q&A reveal slide (non-live)
Answer (static)	::answer …	Answer text for Q&A layout

# 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

:::voice
Narration for AI voice / video.
:::

:::note
Speaker notes — not shown on slide.
:::

Themes

bright-scholar, hsk-classroom, qz-grammar-pro, chinese-classic, dark-tech, minimal-white

Rules for AI-generated content

1. Do not invent facts beyond the source
2. One idea per slide; max 3–5 short bullets
3. Long text in :::voice, not on slide
4. Missing data → [NEEDS INPUT] / [CẦN BỔ SUNG]
5. Preserve Chinese, pinyin, glosses
6. Output plain Markdown — no ```markdown wrapper (see AI Prompt Kit OUTPUT PROTOCOL)

Example deck

example-deck.md — 3-slide sample