Widget Markdown Syntax
The :::widget-type(config) syntax for defining game widgets in text.
Behind every interactive widget in the Lex Editor is a markdown-based syntax. When you insert a widget through the toolbar or slash commands, the editor generates this syntax automatically. You do not need to write it by hand -- but understanding it is useful for advanced users, AI prompt engineering, and troubleshooting.
This page documents the DSL (Domain-Specific Language) used to define widgets in lesson content.
Syntax Overview
Inline Widgets
Inline widgets sit within a line of text:
___(correct_answer) -- fill-in-the-blank
___(correct, wrong1, wrong2) -- multiple choice dropdownBlock Widgets
Block widgets use the fenced ::: syntax:
:::widget-type(config_params)
content lines
:::The opening ::: line specifies the widget type and optional configuration parameters. Content lines define the widget data. The closing ::: ends the block.
Fill-in-the-Blank (AnswerInput)
Syntax: ___(correct_answer)
The simplest inline widget. Place it anywhere in a sentence where you want a text input field.
Basic Usage
She ___(went) to the store yesterday.Multiple Accepted Answers
Separate alternatives with a pipe |:
She ___(went|visited) the museum.With Hint
Add a hint in parentheses after the answer definition:
She ___(went) (to go) to the store.The hint text (the base form "to go") is shown to the student as a clue.
How It Is Detected
If the content inside ___() has no comma, it is parsed as an AnswerInput (fill-in-the-blank). If it has commas, it becomes an AnswerCombo (dropdown).
State Export
When a student has answered, the state is exported as:
___(correct)[wrong1, wrong2, =correct]The [ATTEMPTS] section records the student's attempts. = marks the final correct answer.
Multiple Choice Dropdown (AnswerCombo)
Syntax: ___(correct, wrong1, wrong2, wrong3)
An inline dropdown where the student selects from options.
Basic Usage
Yesterday, I ___(went, go, going, gone) to the store.The first item is always the correct answer. Items after commas are distractors. The display order is shuffled automatically.
Multiple Correct Answers
Use a pipe | for alternatives:
___(went|visited, go, going) to the store.With Hint
___(went, go, going, gone) (to go)State Export
___(went, go, going, gone)[going, =went]Records the student's wrong attempts followed by the correct selection.
Matching Widget
Syntax: :::matching(config)
A click-to-connect pairing exercise.
Basic Usage
:::matching(pair_type="word-translation")
- apple :: яблоко
- cat :: кот
- house :: дом
- car :: машина
:::Each line defines a pair with left :: right format.
With Distractors
Add items with no correct pair using !!:
:::matching(pair_type="word-translation")
- apple :: яблоко
- cat :: кот
- house :: дом
- !! мышка
:::The !! item appears in the right column but has no matching left-side item.
Configuration Parameters
| Parameter | Values | Default |
|---|---|---|
pair_type | word-translation, sentence-completion, image-word, audio-word | word-translation |
shuffle | true, false | true |
ui | classic, children | classic |
instruction | any string | (none) |
State Export
:::matching(pair_type="word-translation")
- apple :: яблоко [✓]
- cat :: кот [✓]
- house :: дом [✗:машина]
- car :: машина []
- !! мышка
:::[✓] = correct, [✗:selected] = wrong (shows what was selected), [] = unanswered.
Ordering Widget
Syntax: :::ordering(config)
A drag-and-drop sequencing exercise.
Sentence Ordering
:::ordering(type="sentences")
1. First, preheat the oven.
2. Then, mix the ingredients.
3. Next, pour into the pan.
4. Finally, bake for 30 minutes.
:::Items are listed in the correct order. The editor shuffles them for the student.
Word Ordering
:::ordering(type="words" hint="I")
1. I
2. have
3. never
4. been
5. to
6. Paris
:::Configuration Parameters
| Parameter | Values | Default |
|---|---|---|
type | sentences, words | sentences |
hint | any string (e.g., first word) | (none) |
ui | classic, children | classic |
State Export
:::ordering(type="sentences") [order:3,1,2,4][correct:false]
1. First, preheat the oven.
2. Then, mix the ingredients.
3. Next, pour into the pan.
4. Finally, bake for 30 minutes.
:::[order:...] shows the student's current arrangement. [correct:true/false] shows whether it matches.
Sentence Builder
Syntax: :::sentence-builder(config)
Students drag word tiles to build a sentence.
Basic Usage
:::sentence-builder(instruction="Build the correct sentence")
The cat sat on the mat
:::The first line is the target sentence. Each word becomes a tile in a shuffled word bank.
With Distractors
:::sentence-builder(instruction="Build the correct sentence")
The cat sat on the mat
!! dog
!! under
:::Lines starting with !! add extra words to the bank that do not belong in the sentence.
Configuration Parameters
| Parameter | Values | Default |
|---|---|---|
instruction | any string | (none) |
hint | any string | (none) |
shuffle | true, false | true |
ui | classic, children | classic |
State Export
:::sentence-builder(instruction="Build the correct sentence") [sentence:0,1,2,3,4,5][bank:6,7][correct:true]
The cat sat on the mat
!! dog
!! under
:::Indices map into allWords = [...correctWords, ...distractors]. [sentence:...] = words placed in the sentence zone. [bank:...] = words remaining in the bank.
True/False Widget
Syntax: :::true-false(config)
A series of statements to evaluate as true or false.
Basic Usage
:::true-false
- [T] The Earth orbits the Sun. // It completes one orbit every 365.25 days.
- [F] The Moon is larger than the Earth. // The Moon's diameter is about 1/4 of Earth's.
- [T] Water boils at 100 degrees Celsius at sea level.
:::[T] marks a true statement, [F] marks a false one. Text after // is the explanation shown after answering.
Configuration Parameters
| Parameter | Values | Default |
|---|---|---|
showExplanation | true, false | true |
ui | classic, children | classic |
State Export
:::true-false
- [T][✓] The Earth orbits the Sun. // explanation
- [F][✗:T] The Moon is larger than the Earth. // explanation
- [T][] Water boils at 100 degrees Celsius at sea level.
:::[✓] = answered correctly, [✗:T] = answered wrong (student selected True), [] = unanswered.
Flashcard Widget
Syntax: :::flashcard(config)
:::flashcard(card_type="word-translation")
- apple | яблоко
- cat | кот
- house | дом (hint: place where you live)
:::Each line defines a card: front | back. Optional hint in parentheses.
Configuration Parameters
| Parameter | Values | Default |
|---|---|---|
card_type | word-translation, word-definition, word-image, sentence-translation | word-translation |
showProgress | true, false | true |
shuffle | true, false | true |
Memory Game Widget
Syntax: :::memory-game(config)
:::memory-game(pair_type="word-translation" grid="3x4")
- apple :: яблоко
- cat :: кот
- house :: дом
- dog :: собака
- book :: книга
- tree :: дерево
:::Configuration Parameters
| Parameter | Values | Default |
|---|---|---|
pair_type | word-translation, word-image, word-definition | word-translation |
grid | 2x3, 2x4, 3x4, 4x4, 4x5 | auto |
timeLimit | seconds | (none) |
showTimer | true, false | true |
Word Scramble Widget
Syntax: :::word-scramble(config)
:::word-scramble(hint_type="translation")
- apple (яблоко)
- beautiful (красивый)
- elephant (слон)
:::Each line: word (hint).
Configuration Parameters
| Parameter | Values | Default |
|---|---|---|
hint_type | translation, image, definition, first-letter, none | translation |
attemptsPerWord | number | unlimited |
Category Sort Widget
Syntax: :::category-sort(config)
:::category-sort(layout="horizontal")
## Nouns
- apple
- house
- cat
## Verbs
- run
- eat
- sleep
:::Categories are defined with ## Category Name, items listed below each.
Configuration Parameters
| Parameter | Values | Default |
|---|---|---|
layout | horizontal, vertical | horizontal |
showFeedback | immediate, on-submit | on-submit |
Word Search Widget
Syntax: :::word-search(config)
:::word-search(grid_size=10 directions="horizontal,vertical")
- apple (яблоко)
- house (дом)
- cat (кот)
:::Configuration Parameters
| Parameter | Values | Default |
|---|---|---|
grid_size | number (grid dimension) | 10 |
directions | horizontal, vertical, diagonal (comma-separated) | horizontal,vertical |
showWordList | true, false | true |
timeLimit | seconds | (none) |
Crossword Widget
Syntax: :::crossword(config)
:::crossword(hints_allowed=3)
- apple : A red or green fruit
- cat : A small furry pet that purrs
- house : A building where people live
:::Each line: word : clue.
Configuration Parameters
| Parameter | Values | Default |
|---|---|---|
hints_allowed | number | 3 |
checkMode | word, puzzle | word |
Other Block Syntax
Audio Player
:::audio(src="/media/audio.mp3" title="Dialogue" transcript="after-listen")
Optional transcript text here
:::Speech Recorder
:::speech(prompt="Read the following text aloud" maxDuration=60)
The quick brown fox jumps over the lazy dog.
:::Essay Block
<essay>
Sentence starter here...
</essay>Annotation (Teacher-Only)
<annotation>
Teaching notes visible only to the teacher.
</annotation>Exercise Container
<exercise>
Exercise content with AnswerInput/AnswerCombo nodes inside.
</exercise>Table with Fill-in Cells
Standard markdown tables can include ___() syntax inside cells:
| Form | "go" | "be" |
|------|------|------|
| Present | ___(go) | ___(am) |
| Past | ___(went) | ___(was) |Answer Notes Rule
The :::matching, :::ordering, :::sentence-builder, and :::true-false blocks already encode correct answers in their syntax. If you need to add an answer key or explanation summary after these blocks, wrap it in <annotation> tags so only the teacher sees it. Otherwise, the answers would be visible to students in the lesson content.
Frequently Asked Questions
Do I need to write this syntax by hand?
No. The editor generates the correct syntax when you use the toolbar or slash commands. This reference is for advanced users, troubleshooting, and understanding how AI-generated content works.
What happens if the syntax has an error?
The post-processor validates widget syntax during save. Malformed widgets may be displayed as plain text or trigger a warning in the editor.
Can I copy and paste widget syntax?
Yes. You can copy widget markdown from one lesson and paste it into another. The editor will parse and render it correctly.
Is the syntax the same as standard Markdown?
The inline syntax (___()) and the fenced block syntax (:::) are extensions to standard Markdown. They are specific to the Lex Editor and will not render in other Markdown processors.
How does the AI lesson builder use this syntax?
The AI generates lesson content as markdown, including widget syntax. The post-processor then parses the markdown into Lexical editor nodes. Understanding the syntax helps you read and modify AI-generated content.