ReadingBat Template

A Kotlin/Ktor template for teachers to author ReadingBat.com content — a code-reading practice site inspired by CodingBat.com.

ReadingBat helps students learn to read and trace code before they start writing it. Challenges are defined using a Kotlin DSL and support Python, Java, and Kotlin.

This template lets you create your own ReadingBat content. Once it's ready, send us a note and we'll link ReadingBat.com to it.

Prerequisites

• Java 17+ (the project uses a JVM 17 toolchain)
• Git (to clone the repo and manage content)

Gradle is included via the Gradle Wrapper — no separate install needed.

Getting Started

git clone https://github.com/readingbat/readingbat-template.git
cd readingbat-template
./gradlew build -xtest   # compile without running tests
./gradlew run            # start the server on http://localhost:8080

See the wiki for more details: Quickstart | Setup | Running a Server

Build & Run Commands

Command	Description
./gradlew build -xtest	Compile without tests
./gradlew run	Start the dev server (port 8080)
./gradlew --rerun-tasks check	Run all tests
./gradlew test --tests "ContentTests"	Run a single test class
./gradlew buildFatJar	Build a fat JAR (build/libs/server.jar)
./gradlew build --continuous -xtest	Continuous compile on file changes
./gradlew lintKotlin detekt	Run Kotlinter (ktlint) and detekt
./gradlew formatKotlin	Auto-format Kotlin sources with ktlint
./gradlew dependencyUpdates	Check for dependency updates

A Makefile is also provided with shorthand targets (make build, make run, make tests, make lint, make format, etc.). Run make help to see every documented target.

Project formatting is governed by .editorconfig (UTF-8, LF, 2-space indent, 120-char max). Lint via Kotlinter (ktlint) + detekt; both are wired in as Gradle plugins.

Project metadata (group, version) is set in gradle.properties. Dependency versions and the testing bundle are defined in gradle/libs.versions.toml.

Content Specification

Specify ReadingBat content with the ReadingBat-specific Kotlin DSL. Using the DSL does not require in-depth knowledge of Kotlin.

ReadingBat supports challenges written in 3 languages: Python, Java and Kotlin.

Specify the content in the src/main/kotlin/Content.kt file.

The structure of the DSL is:

val content =
  readingBatContent {
    python {                                    // Creates a LanguageGroup object
      group("Group 1") {                        // Creates a ChallengeGroup named "Group 1"
        packageName = "group1"                  // The path of the challenges in this group
        description = "Description of **Python** Group 1" // Descriptions support markdown

        challenge("find_it") {                  // Creates a Challenge for group1/find_it.py
          returnType = BooleanType              // Challenge return type
        }

        challenge("boolean2") {                 // Creates a Challenge for group1/boolean2.py
          returnType = BooleanType              // Challenge return type
        }

        // Include all challenges matching the "slice*.py" filename pattern
        includeFilesWithType = "slice*.py" returns StringType
      }
    }

    java {
      group("Group 1") {
        packageName = "group1"
        description = "Description of **Java** Group 1"

        challenge("JoinEnds") {                 // Java Return types are inferred from the code
          codingBatEquiv = "p141494"            // Will add a link to this codingbat.com challenge
        }

        challenge("ReplaceCheck")               // Creates a Challenge for group1/ReplaceCheck.java

        // Include all challenges matching the "Has*.java" filename pattern
        includeFiles = "Has*.java"
      }
    }

    kotlin {
      group("Group 1") {
        packageName = "kgroup"
        description = "Description of **Kotlin** Group 1"

        challenge("StringLambda1") {
          returnType = StringType
        }

        // Include all challenges matching the "lambda*.kt" filename pattern
        includeFilesWithType = "lambda*.kt" returns StringType
      }
    }
  }

DSL Objects

• ReadingBatContent
• LanguageGroup
• ChallengeGroup
• Challenge

Challenge Code

Challenge source files live in language-specific directories:

Language	Directory	Example
Python	python/<packageName>/	python/group1/find_it.py
Java	src/main/java/<packageName>/	src/main/java/group1/JoinEnds.java
Kotlin	src/main/kotlin/<packageName>/	src/main/kotlin/kgroup/StringLambda1.kt

Wiki references: Python | Java | Kotlin

Server Configuration

Server settings are in src/main/resources/application.conf (HOCON format). See the Server Configuration wiki page for details.

Examples

The readingbat-site repo powers ReadingBat.com and combines content from multiple repos:

Content.kt files:

• Top-level Content.kt
• Java and Kotlin Content
• Python Content

Challenge source code:

• Python
• Java
• Kotlin

More Resources

• Kotlin Tips
• GitHub Tips