exercise-syntax

Exercise Syntax Rules

Exact syntax rules for the interactive exercises Quarto extension (_extensions/exercises/). These rules are non-negotiable: exercises that violate them will silently break (render as raw text, fail to submit, or crash with JS errors).

The extension uses a Lua filter that walks the Pandoc AST. Pandoc parses the markdown before the filter runs, so the markdown must produce the exact AST structures the filter expects.

---

General Rules (All Exercise Types)

1. Blank lines before and after every exercise block. The outer ::: {.exercise-*} and closing ::: must have blank lines above and below them.

2. Options MUST use bullet list syntax (- Option text), on consecutive lines with NO blank lines between items. Pandoc parses - item as a BulletList node; the Lua filter searches for BulletList. If you use standalone paragraphs, numbered paragraphs, or lettered paragraphs (like A. text with blank lines), Pandoc will parse them as separate Para nodes and the filter will not find the options.

# CORRECT — consecutive bullet items, no blank lines between:
- Option text one
- Option text two
- Option text three

# WRONG — standalone paragraphs (Pandoc sees Para, not BulletList):
A. Option text one

B. Option text two

C. Option text three

# WRONG — numbered list (Pandoc sees OrderedList, not BulletList):
1. Option text one
2. Option text two
3. Option text three

1. Do NOT prefix options with letter labels in any format: A), B), A., B., [A], [B], etc. The Lua filter auto-assigns labels A, B, C, D based on list order. These prefixes break in different ways: A) triggers Pandoc's ordered list parser producing <ol type="A">, while [A] renders as literal bracket text inside the option card, duplicating the auto-assigned label.

# CORRECT — plain text, labels auto-assigned:
- An agent uses a larger language model
- An agent has a decision procedure that controls a loop
- An agent always uses multiple tools simultaneously

# WRONG — "A)" triggers Pandoc's ordered list parser:
- A) An agent uses a larger language model
- B) An agent has a decision procedure

# ALSO WRONG — "[A]" renders as duplicate label text:
- [A] An agent uses a larger language model
- [B] An agent has a decision procedure