TeXSmith Exam

texsmith-exam is an exam-focused template for TeXSmith.
It provides:

• An exam template for both backends — LaTeX (exam.cls) and Typst — and the IR pass that reads the exam constructs for either.
• TMark spellings for question structures, multiple-choice answers, and fill-in blanks.
• Solution-aware rendering to generate both student and answer-key PDFs from the same source.
• Demo content and Makefiles to quickly produce sample exam/solution outputs.

The current template branding is oriented to HEIG-VD and can be adapted over time.

What it is

This repository contains:

• A TeXSmith template entry point: exam.
• An IR pass declared by the template manifest (texsmith 0.9), which reads:
  • Heading-to-question/part/subpart mapping.
  • Task-list-based multiple-choice blocks.
  • Solution containers (::: solution) with lines/grid/box options.
  • Fill-in-the-blank placeholders.
• Documentation source under docs/.
• Working demos under demo/exam and demo/quiz.

Prerequisites

• Python >=3.13
• TeXSmith >=0.9,<1.0 — the template's IR pass and both emitters need it
• uv installed
• A LaTeX environment available for TeXSmith PDF builds, or typst for the Typst backend

Installation

From repository root:

uv sync --group dev --group docs

This installs runtime deps, dev/test tools, and docs tooling.

How to use

1. Prepare your exam markdown

Create one or more .md files using the exam syntax documented in:

• docs/index.md
• docs/syntax.md

Optional front matter can define title, author, language, and exam.* settings (see demo/exam/config.yml for a complete example).

2. Render with the installed template entry point

If the package is installed in your environment, use:

uv run texsmith render --template exam exam.md

Generate solution version from the same source:

uv run texsmith render --template exam -a solution=true exam.md

3. Render with the local template path (dev workflow)

From this repository, use the local template directly:

uv run texsmith -t src/texsmith_template_exam/exam exam.md --build

Solution mode:

uv run texsmith -t src/texsmith_template_exam/exam exam.md --build -a solution=true

4. Run the provided demos

Build exam + solution PDFs for the full demo:

make -C demo/exam

Outputs:

• demo/exam/build/exam/exam.pdf
• demo/exam/build/solution/solution.pdf

Build quiz demo:

make -C demo/quiz

Clean demo build artifacts:

make -C demo/exam clean
make -C demo/quiz clean

Build and use documentation

Serve docs locally (live reload)

uv run mkdocs serve

Then open http://127.0.0.1:8000.

Build static docs

uv run mkdocs build

Generated site output is in site/.

Development checks

Run tests:

uv run pytest

Run lint/format checks:

uv run ruff check .
uv run ruff format .

Repository layout

• src/texsmith_template_exam/: package source
• src/texsmith_template_exam/exam/: template assets and manifest
• docs/: MkDocs documentation
• demo/: runnable examples
• tests/: automated tests

Extension points

• Renderer handlers: src/texsmith_template_exam/exam_renderer.py delegates to domain modules in src/texsmith_template_exam/exam/.
• Markdown extensions: src/texsmith_template_exam/markdown.py exports exam_markdown_extensions().
• Template filters: src/texsmith_template_exam/exam/__init__.py registers markdown_to_latex, exam_date, exam_version.
• Compatibility layer for texsmith internals: src/texsmith_template_exam/exam/texsmith_compat.py.