4. Gapfill Directive Documentation

The gapfill directive creates an interactive “Fill-in-the-Blanks” text or code exercise. Users can select the correct terms from inline dropdown boxes embedded directly within the paragraph or code structure.

4.1. Syntax

.. gapfill::

    Your text goes here with a @@correct_option | incorrect_1 | incorrect_2@@ placeholder.

4.2. Options for the gapfill directive

Option	Type	Description
`:theme:`	string	Set the visual theme. Options are `light` (default) or `dark`.

Syntax Rules: Inline dropdown segments are declared using the sequence format
@@correct | incorrect | incorrect_2@@.
Correct Answer: The first element inside the bracketed option block represents the correct target validation key.
Shuffling: The directive automatically shuffles options alphabetically when rendering choices to prevent positioning giveaways.
Dual-Option Fallback: If you only specify a single word like @@answer@@, the directive automatically generates a generic placeholder fallback choice.

4.3. Example 1: Single Sentences

The following example demonstrates a simple gap with 2 alternative choices.

The correct answer is the first option in the list.

.. gapfill::

    In Python, boolean values must be capitalized as @@True | true | TRUE@@ or False.

In Python, boolean values must be capitalized as  or False.

4.4. Example 2: Dark theme

The following example demonstrates the gapfill directive with the dark theme. :theme: dark is optional since it is not the default.

.. gapfill::
    :theme: dark

    To execute code conditionally, use the @@if | None | else@@ keyword followed by an expression.

To execute code conditionally, use the  keyword followed by an expression.

4.5. Example 3: Single Parameter

The following example shows what happens when omitting an alternative choice option. The directive creates an alternative fallback choice automatically.

.. gapfill::

    Python is an @@interpreted@@ programming language.

Python is an  programming language.

4.6. Example 4: Multiple Options inside Code Snippets

The example shows the preservation of indentation and formatting within the code block, while still allowing for interactive selection of choices from a dropdown menu.

.. gapfill::

    def find_max(numbers):
        max_val = numbers[@@0 | 1@@]
        for num in @@numbers | max_val@@:
            if num @@> | == | <@@ max_val:
                max_val = @@num | 0@@
        return max_val

    @@print | return@@(find_max([1, 5, 9]))

def find_max(numbers):
    max_val = numbers[]
    for num in :
        if num  max_val:
            max_val = 
    return max_val

(find_max([1, 5, 9]))

.. gapfill::

    for number @@in | of@@ [1, 2, 3, 4]:
        if number % 2 == 0:
            @@continue | break | pass@@
        print(number)

for number   [1, 2, 3, 4]:
    if number % 2 == 0:
        
    print(number)