Getting Started

The project uses UV to manage dependencies and virtual environments. So first, install it if you haven’t already: https://docs.astral.sh/uv/getting-started/installation/

Building themes

Build themes using make themes or directly executing commands specified by the Makefile for target themes.

Building example course

cd example-course
uv run it4kt-builder serve

Running tests

uv run pytest

Running linters

uv run mypy it4kt tests
uv run ruff check

or using make:

make lint

Architecture decisions

Important decisions and concepts of the IT4KT Builder are documented using Architecture Decision Records (ADR). The concept of ADR is described in the article Documenting Architecture Decisions by Michael Nygard.

Accepted ADRs

• ADR 1: Model — how the Builder works
• ADR 2: Themes without XSLT — how themes work
• ADR 3: Folders — how the content is structured into folders
• ADR 4: URLs mirroring paths in source directory
• ADR 5: Environment
• ADR 7: GitLab CI as build server
• ADR 8: Auto-updating build scripts
• ADR 9: Markdown
• ADR 10: Tracking weeks
• ADR 11: Content directory
• ADR 12: Declarative configuration
• ADR 13: Virtualized Filesystem
• ADR 14: Localization
• ADR 15: Declarative Kpimark validation

Deprecated and superseded ADRs

• ADR 6: Direct processors configuration

Themes

Structure of the generated HTML

Generated HTML uses the BEM naming convention with two dashes for modifiers. The main blocks are the following:

• section — main element of the page structure,
• step — step of the scenario
• special blocks inside the content
  • task
  • lecturer — note visible only by lecturer
  • admonition — notes and warnings for students

Structure of the blocks and examples are in the reference HTML page.