Dynamic & Interactive Elements

ZiraDocs goes beyond static presentations by supporting dynamic and interactive elements that engage your audience and make presentations more memorable. These features help transform presentations from monologues into engaging dialogues.

Accuracy note. Of everything on this page, what ships today is <<quiz>> and <<poll>>, documented in the next section. Everything else is aspirational: the parser has no element for it, and a deck that uses those forms gets SPECIAL001: Unknown special block type and no behaviour. That covers every ::: block on this page — :::qa_session, :::reveal_content, :::reveal, :::embed, :::form, :::branch_buttons, :::navigation, :::whiteboard — the strict-mode REVEAL_GROUP and BRANCH_BUTTON keywords, the audience analytics, and every {{poll.*}} / {{analytics.*}} interpolation. They are kept for roadmap context and are being reconciled separately in ziradocs/website#11.

There is also no backend. A quiz and a poll are static documents with a little client-side JavaScript: whatever a viewer clicks stays in that viewer’s browser. Nothing is collected, aggregated or shared between people opening the same deck.

Overview

What ships:

• Quizzes - a question, its options, which one is right, and an optional explanation
• Polls - a question and its options, with no right answer

What does not ship yet (see the note above):

• Q&A systems, reveal content, embedded content, forms, whiteboards
• Non-linear navigation and branching
• Audience analytics and real-time response counts

Interactive Elements

Quizzes and polls

Requires v2.32.4 or newer. A v2.26.0 binary does not know these tags; see Installation for what it does with them.

<<quiz>> and <<poll>> are the two interactive elements the parser has. Both carry a YAML body, unlike every other embedded element, and both work in flex and strict, in SlideLang and DocLang alike.

Quiz

<<quiz>>
question: "Which type of ML would you use for email spam detection?"
options:
  - "Unsupervised learning"
  - "Supervised learning"
  - "Reinforcement learning"
answer: 1
explanation: "We have labelled examples of spam and legitimate email."
<<end>>

Poll

<<poll>>
question: "What's your programming experience level?"
options: ["Beginner", "Intermediate", "Advanced", "Expert"]
multiple: false
<<end>>

The keys

Key	Element	Meaning
question	both	The prompt.
options	both	A YAML list or an inline array — both forms are accepted.
answer	quiz	0-based index of the correct option: answer: 1 selects the second one.
explanation	quiz	Shown once the question is answered. Optional.
multiple	poll	Lets the viewer pick more than one option. Optional, defaults to false.

A key outside that set is reported and ignored rather than dropped in silence (QUIZ005 / POLL004), and a body that is not valid YAML is reported as QUIZ004 / POLL003 — the block is still consumed either way, so nothing after it gets reprocessed as prose.

<<end>> is the canonical closer. <</quiz>> and <</poll>> are also accepted, the same way <</chart>> is.

The linter flags a quiz whose answer is out of range as an error (QUIZ001), which is the mistake worth failing a build over: it silently marks the wrong option right. Fewer than two options, or a missing question, are warnings.

What the output actually does

In SlideLang HTML, the options are buttons. Clicking one marks it, reveals the correct one and shows the explanation; a poll toggles the selection and fills in bars from what that viewer picked. All of it is local to the browser that opened the file.

Everywhere else there is no interaction: a quiz renders with the correct option already marked and its explanation visible, which is what a printed answer key should look like. That covers SlideLang’s pdf and pptx, and all of DocLang’s formats — html, pdf, docx and markdown. (SlideLang emits json, html, pdf and pptx; it has no DOCX or Markdown output.)

Q&A Sessions

Integrate structured question and answer sessions into your presentations.

Flex Mode:

## Q&A Session

Submit your questions using the form below:

:::qa_session id="main_qa" moderation="true"
**Guidelines:**
- Keep questions concise and relevant
- One question per submission
- Questions will be moderated before display
:::

**Submitted Questions:** {{qa.main_qa.count}}

Use Cases:

• Webinars - Collect questions throughout the presentation
• Training sessions - Address specific participant concerns
• Corporate meetings - Structured feedback collection

Progressive Content Reveal

Show content progressively to maintain audience focus and build suspense.

Flex Mode:

## Implementation Steps

:::reveal
### Phase 1: Planning
- **Timeline:** 2 weeks
- **Deliverables:** Project scope, requirements

:::reveal_content
**Detailed Planning Activities:**
- Stakeholder interviews (3 days)
- Requirements gathering (5 days)
- Technical feasibility analysis (3 days)
- Resource allocation planning (3 days)
:::

### Phase 2: Development
- **Timeline:** 6 weeks
- **Deliverables:** MVP, testing suite

### Phase 3: Deployment
- **Timeline:** 2 weeks
- **Deliverables:** Production release, documentation
:::

Strict Mode:

SLIDE process
  title: "Implementation Roadmap"
  REVEAL_GROUP
    ITEM "Phase 1: Planning (2 weeks)"
      DETAILS
        TEXT "Stakeholder interviews, requirements gathering"
        TEXT "Technical feasibility and resource allocation"
    ITEM "Phase 2: Development (6 weeks)"
    ITEM "Phase 3: Deployment (2 weeks)"

Embedded Content

Video Integration

Embed videos directly in your presentations for rich multimedia experiences.

YouTube Videos:

## Product Demo

Watch our latest feature demonstration:

:::embed type="youtube" video_id="dQw4w9WgXcQ"
width="100%" height="400px" autoplay="false"
:::

**Key takeaways from the demo:**
- Improved user interface
- 40% faster performance
- Enhanced security features

Direct Video Files:

## Training Video

:::embed type="video"
src="assets/training-module-1.mp4"
controls="true" width="800" height="450"
:::

Interactive Maps

Display geographic data and locations with interactive maps.

Simple Location Map:

## Our Office Locations

:::embed type="iframe"
src="https://www.openstreetmap.org/export/embed.html?bbox=-74,40,-73,41"
width="100%" height="400px"
:::

**Headquarters:** New York, NY
**Regional Offices:** London, Tokyo, Sydney

Dashboard Embeds

Include live dashboards and analytics in your presentations.

## Real-Time Performance

:::embed type="iframe"
src="https://dashboard.company.com/public/sales-overview"
width="100%" height="500px"
sandbox="allow-scripts allow-same-origin"
:::

**Data updated:** Every 5 minutes
**Metrics shown:** Sales, conversions, user activity

Dynamic Data Integration

Real-Time Variables

Use dynamic variables that update during the presentation.

Live Session Data:

---
variables:
  session_participants: ${live.participants}
  current_time: ${live.timestamp}
  poll_responses: ${poll.tech_stack.total_responses}
---

## Welcome to Our Webinar

**Current attendees:** {{session_participants}}
**Session time:** {{current_time}}
**Poll responses so far:** {{poll_responses}}

API Data Integration

Connect to live data sources for up-to-date information.

---
data_sources:
  sales_api: "https://api.company.com/sales/current"
  weather_api: "https://api.weather.com/current"
  refresh_interval: "5m"
---

## Current Status

**Today's sales:** ${{data.sales_api.today_total|currency}}
**Weather at HQ:** {{data.weather_api.temperature}}°F
**Last updated:** {{data.last_refresh|time}}

Interactive Navigation

Conditional Branching

Create presentations that adapt based on audience choices.

Flex Mode:

## Choose Your Path

What would you like to explore today?

:::branch_buttons
- [Technical Implementation](#technical-deep-dive)
- [Business Overview](#business-case)
- [Use Cases & Examples](#use-cases)
:::

---
id: technical-deep-dive
---

# Technical Deep Dive
*Content for technical audience...*

---
id: business-case
---

# Business Overview
*Content for business stakeholders...*

Strict Mode:

SLIDE choice
  title: "Customize Your Experience"
  TEXT "What's your primary interest?"

  BRANCH_BUTTON "Technical Details" target="tech_slides"
  BRANCH_BUTTON "Business Impact" target="business_slides"
  BRANCH_BUTTON "Implementation" target="implementation_slides"

SLIDE_GROUP tech_slides
  SLIDE technical_overview
    title: "Technical Architecture"
    # Technical content...

Navigation Controls

Add custom navigation elements for non-linear presentations.

## Presentation Menu

:::navigation
- [Introduction](#intro) - Project overview
- [Technical Details](#tech) - Architecture deep-dive
- [Demo](#demo) - Live demonstration
- [Q&A](#qa) - Questions and discussion
- [Next Steps](#next) - Action items
:::

**Current section:** {{navigation.current_section}}
**Progress:** {{navigation.progress}}% complete

Interactive Forms

Feedback Collection

Gather structured feedback during presentations.

## Session Feedback

:::form id="session_feedback"
action="https://api.company.com/feedback"
:::

**How would you rate this session?**
- [ ] Excellent - Exceeded expectations
- [ ] Good - Met expectations
- [ ] Fair - Some improvement needed
- [ ] Poor - Significant issues

**What topics would you like covered next time?**
[ ] Text input field

**Submit Feedback** [Button]

Registration Forms

Capture attendee information and preferences.

## Workshop Registration

:::form id="workshop_signup"
:::

**Personal Information:**
- Name: [ Text input ]
- Email: [ Email input ]
- Company: [ Text input ]

**Session Preferences:**
- [ ] Beginner track
- [ ] Advanced track
- [ ] Custom implementation

**Special Requirements:**
[ ] Textarea for additional notes

**Register Now** [Submit button]

Best Practices

Engagement Guidelines

1. Purpose-driven interactivity - Only add interactive elements that enhance your message
2. Clear instructions - Always explain how to interact with elements
3. Technical testing - Test all interactive features before presentation
4. Backup plans - Have static alternatives ready
5. Accessibility - Ensure interactive elements work with assistive technologies

Performance Considerations

• Load times - Optimize embedded content for fast loading
• Bandwidth - Consider audience internet connection quality
• Device compatibility - Test on mobile devices and tablets
• Graceful degradation - Provide fallbacks for unsupported features

Security & Privacy

• Data collection - Be transparent about data usage
• External content - Validate safety of embedded sources
• User consent - Request permission for data collection
• Secure transmission - Use HTTPS for all external connections

Implementation Examples

Corporate Training Session

---
mode: flex
title: "Employee Onboarding - Day 1"
interactive: true
---

# Welcome to TechCorp! 👋

## Quick Introduction Poll

<<poll>>
question: "What's your role?"
options:
  - "Software Engineer"
  - "Product Manager"
  - "Designer"
  - "Data Scientist"
  - "Other"
<<end>>

---

## Training Modules

:::reveal
### Module 1: Company Culture
**Duration:** 30 minutes

:::reveal_content
**Learning objectives:**
- Understand company values
- Learn communication protocols
- Explore collaboration tools

**Interactive elements:**
- Culture quiz
- Virtual office tour
- Team introductions
:::

### Module 2: Tools & Systems
**Duration:** 45 minutes

### Module 3: First Project
**Duration:** 60 minutes
:::

---

## Live Q&A

:::qa_session id="onboarding_qa" moderation="false"
**Ask anything about:**
- Company policies
- Tools and systems
- Team structure
- Growth opportunities
:::

**Questions submitted:** {{qa.onboarding_qa.count}}

Sales Presentation

---
mode: flex
title: "Product Demo - Q4 2024"
variables:
  prospect_name: "Acme Corp"
  demo_date: "2024-12-15"
---

# Welcome {{prospect_name}}!

## Agenda Customization

What would you like to focus on today?

<<poll>>
question: "What would you like to focus on today?"
options:
  - "Technical capabilities"
  - "ROI and pricing"
  - "Implementation timeline"
  - "Support and training"
  - "Integration options"
multiple: true
<<end>>

---

## Live Product Demo

:::embed type="iframe"
src="https://demo.ourproduct.com/live-demo"
width="100%" height="600px"
:::

**Demo environment:** Customized for {{prospect_name}}
**Data shown:** Representative of your use case

---

## Implementation Planning

:::branch_buttons
- [Pilot Program](#pilot) - Start small, 30-day trial
- [Full Deployment](#full) - Enterprise-wide rollout
- [Custom Solution](#custom) - Tailored implementation
:::

---
id: pilot
---

## Pilot Program Details

**Timeline:** 30 days
**Users:** Up to 50 team members
**Support:** Dedicated success manager
**Investment:** ${{pricing.pilot|currency}}/month

:::form id="pilot_interest"
**Express interest in pilot program:**
- Contact: [ Email input ]
- Preferred start date: [ Date input ]
- Team size: [ Number input ]

**Request Pilot** [Submit]
:::

Advanced Features

Real-Time Collaboration

Enable multiple presenters and audience interaction:

---
collaboration:
  co_presenters: ["john@company.com", "sarah@company.com"]
  audience_questions: true
  live_annotations: true
  shared_whiteboard: true
---

## Collaborative Session

**Current presenters:** {{collaboration.active_presenters}}
**Audience size:** {{collaboration.audience_count}}
**Questions queue:** {{collaboration.questions_pending}}

:::whiteboard id="main_board"
tools="pen,highlighter,shapes"
collaborative="true"
:::

Analytics Integration

Track engagement and presentation effectiveness:

---
analytics:
  track_engagement: true
  heatmap_tracking: true
  poll_analytics: true
  completion_tracking: true
---

## Presentation Analytics

**Current engagement:** {{analytics.engagement_score}}%
**Slide attention:** {{analytics.current_slide_time}}s
**Most engaging:** Slide {{analytics.top_slide}}
**Poll participation:** {{analytics.poll_participation}}%

Related Documentation

• Advanced Elements - Charts, maps, and rich media
• Special Blocks - Interactive block elements
• Variables & Templates - Dynamic content management
• Themes & Styling - Customizing interactive element appearance

Future Roadmap

Planned interactive features include:

• Voice interaction - Voice-controlled navigation
• AR/VR support - Immersive presentation experiences
• AI integration - Smart content recommendations
• Advanced analytics - Machine learning insights
• Real-time translation - Multi-language audience support

---

Quizzes and polls need no setup: the JavaScript that drives them is emitted with the deck, and only when the deck actually contains one. In the non-HTML formats they render statically, with the quiz’s correct option already marked.