DOCSEARCHbyAlgolia
Submit Docs

text2qti

repository·master·Indexed 42 days ago

https://github.com/gpoore/text2qti

A tool that converts Markdown-based plain text files into QTI version 1.2 formatted quizzes for import into Canvas and other educational platforms. It supports multiple-choice, multiple-answer, numerical, short-answer, essay, and file-upload questions, as well as LaTeX math, images, and dynamic question generation via executable code blocks.

Tokens
5K
Snippets
26
Records
29
Agent score
52%

What's inside text2qti

  1. Create question groups with random selection

    master

    You can group multiple questions together and instruct text2qti to randomly select a subset of them for each quiz attempt.

    To define a group, wrap the questions in GROUP and END_GROUP tags. Use the following metadata keys inside the group header:

    • pick: <number>: Specifies how many questions to select from the group. Defaults to 1 if omitted.
    • points per question: <number>: Specifies the point value for each question in the group. Defaults to 1 if omitted. Note that all questions within a single group must have the same point value.

    All questions within the group must follow the standard Markdown-based quiz format.

    GROUP
pick: 1
points per question: 1

1.  A question.
*a) true
b)  false

2.  Another question.
*a) true
b)  false

END_GROUP

  2. Formatting descriptions, questions, choices, feedback, and text regions

    master

    These elements can span multiple paragraphs and include arbitrary Markdown (code blocks, quotations, etc.).

    Indentation Rule: Everything must be indented to at least the same level as the start of the first paragraph on the initial line.

    Exceptions:

    • Short-answer acceptable answers: Treated as plain text and limited to a single line.
    • Numerical answers: Processed specially and limited to a single line.
    1.  A question paragraph that is long enough to wrap onto a second line.
    The second line must be indented to match up with the start of the
    paragraph text on the first line.

    Another paragraph.

  3. Writing quiz, question, and text region titles

    master

    Titles for quizzes, questions, and text regions are treated as plain text (not Markdown) due to QTI limitations.

    Rules for Titles:

    • They are limited to a single paragraph.
    • If a title wraps across multiple lines, all lines after the first must be indented by at least two spaces or one tab, and must share the same indentation.
    • Titles are optional, but if used, they must appear first, before any other attributes for that element.

  4. Include question-specific information only in solutions

    master

    You can provide information (like grading criteria for essays) that appears in the exported solutions but is never included in the QTI file.

    To do this, use an exclamation point ! for the solution syntax. This is distinct from feedback syntax (which uses ..., +, or -).

    Example syntax:

    1.  Write an essay about text2qti.

!   This is important information about what the essay should cover.

    This will only appear in the solutions.

____

  5. Use executable code blocks to generate questions

    master

    You can use Markdown-style fenced code blocks to dynamically generate quiz content. The code is executed, and its stdout replaces the code block in the final quiz file.

    Requirements

    • Top-level placement: Code block fences (```) must not be indented. They must be at the top level of the document, not nested inside a question, choice, or feedback.
    • Security: Code execution is disabled by default. You must enable it using one of these methods:
      • Run the CLI with the --run-code-blocks flag.
      • Set run_code_blocks = true in a .text2qti.bespon config file located in your user or home directory.
    • Syntax: The opening fence must follow the pattern ```{.lang .run} or ```{.lang .run executable=<executable>}.

    Executable Modes

    1. Language-based: If you use {.lang .run}, text2qti uses the lang token to find an executable (e.g., python), saves the code to a temporary file, and runs lang <file>.
    2. Explicit Executable: If you use {.lang .run executable="path/to/exe"}, the lang token is ignored (used only for syntax highlighting), and the specified executable is used to run the code.

    Python Specifics

    When using .python, text2qti will attempt to use python3 if python3 exists and python is equivalent to python2, or if python is missing but python3 exists. To avoid ambiguity, use .python3 or .python2 explicitly.

    Constraints

    • Each code block runs in its own process; variables are not shared between blocks.
    • text2qti will throw an error if a code block generates duplicate questions or duplicate choices within a single question.
    ```{.python .run}
import textwrap
for x in [2, 3]:
    print(textwrap.dedent(rf"""
        1.  What is ${x}\times 5$?
        *a) ${x*5}$
        b)  ${x+1}$
        """))

  6. Adding comments to quiz files

    master

    Comments are completely removed during conversion and do not appear in the final QTI file.

    Top-level Comments (outside questions/choices/feedback):

    • Line comments: Any line starting with % is discarded.
    • Multiline comments: Use COMMENT on a line by itself to start, and END_COMMENT on a line by itself to end. All lines between these delimiters are discarded.

    Inline Comments:

    • Standard HTML comments <!--comment--> can be used within Markdown text and will be stripped out.
    % This is a line comment

COMMENT
This is a
multiline comment
END_COMMENT

This is normal text <!-- and this is an HTML comment -->

  7. Including images in quizzes

    master

    Images use standard Markdown syntax.

    • Local Images: Use relative paths (e.g., ![alt](image.jpg)). Paths not starting with http:// or https:// are treated as local files. If the file is not found, an error is raised.
    • Remote Images: Use full URLs.
    • Path Expansion: Supports ~ for user directory expansion.
    • Pandoc-style Attributes: You can specify IDs, classes, and dimensions directly in Markdown.

    Note: It is recommended to keep image files in the same directory as the quiz file.

    ![alt_text](image_file)
![alt_text](image_file){#id .class1 .class2 width=10em height=5em}

  8. Create a standalone GUI executable for Windows

    master

    You can generate a standalone Windows GUI executable (text2qti_tk_VERSION.exe) using the provided scripts and PyInstaller. This process automates the creation of a dedicated conda environment, installation of dependencies, and the build process.

    Requirements

    • Operating System: Windows
    • Package Manager: conda

    Directions

    1. Ensure you have make_tk_exe.bat and text2qti_tk.pyw in the same directory.
    2. Run the build process using one of the following methods:
      • File Explorer: Double-click make_tk_exe.bat.
      • Command Prompt: Navigate to the directory containing the batch file and run make_tk_exe.bat.
      • PowerShell: Run cmd /c make_tk_exe.bat.

    Build Process Details

    The batch file automates the following workflow:

    1. Creates and activates a new conda environment.
    2. Installs required packages: bespon, markdown, pyinstaller, and text2qti.
      • Note: If the script detects it is part of a local text2qti source tree, it uses the local version. Otherwise, it installs text2qti from PyPI.
    3. Builds the executable using PyInstaller.
    4. Deactivates and removes the temporary conda environment.
    5. Moves the resulting .exe to the working directory and cleans up temporary build files.

  9. Using LaTeX and siunitx math

    master

    text2qti supports inline LaTeX math using dollar signs $.

    Requirements:

    • There must be a non-space character immediately after the opening $ and immediately before the closing $. Example: $F = ma$.
    • Block math is not supported; use inline math only.
    • MathML Conversion: To convert LaTeX to MathML instead of using the default Canvas LaTeX rendering URL, use the --pandoc-mathml CLI flag. This requires Pandoc to be installed. Using this flag creates a _text2qti_cache.zip file to improve performance.

    Customizing Render URL: You can change the default Canvas LaTeX rendering URL by setting latex_render_url = "<URL>" in a .text2qti.bespon configuration file in your home or user directory.

    siunitx Support: Supports a subset of siunitx for scientific notation and units, which can be used inside or outside LaTeX math:

    • \num{1.23e5} $\rightarrow$ 1.23×10⁵
    • \si{m/s} $\rightarrow$ m/s
    • \SI{1.23e5}{m/s}
    • Supported unit macros: \degree, \celsius, \fahrenheit, \ohm, \micro.
    text2qti --pandoc-mathml quiz.txt

  10. Formatting quiz text with Markdown

    master

    text2qti uses Python-Markdown to process most text. You can use standard Markdown notation or HTML for styling.

    Enabled Extensions:

    • smarty: Automatic curly quotes and dashes.
    • sane_lists: Improved list behavior.
    • def_list: Definition lists (term : definition).
    • fenced_code: Fenced code blocks using ``` or ~~~ (preferred over indented blocks).
    • footnotes: Footnotes using [^1] syntax.
    • tables: Pipe-style tables.
    • md_in_html: Markdown inside HTML tags (requires markdown="1" attribute in the opening tag).

    Note: While indented code blocks are supported, fenced code blocks are preferred to avoid interference with the LaTeX and HTML comment preprocessors.

    term
:   definition

[^1]: Footnote text.

| Header | Header |
| ------ | ------ |
| Cell   | Cell   |

  11. Install text2qti

    master

    To use text2qti, you must have Python 3.10+ and setuptools installed. You can install the package via pip.

    # Install setuptools if not present
python -m pip install setuptools

# Install text2qti
python -m pip install text2qti