# Getting Started with tutorizeR

## User goal

This vignette helps an instructor convert one existing `.qmd` or `.Rmd` lesson into an interactive tutorial. The pedagogical goal is to keep one source document while generating student-facing practice material.

## Minimal example

    library(tutorizeR)

    work_dir <- file.path(tempdir(), "tutorizeR-minimal")

    report <- tutorize(
      input = file.path(work_dir, "lesson.qmd"),
      output_dir = work_dir,
      format = "learnr",
      assessment = "both",
      overwrite = TRUE
    )

    print(report)

The report records the input file, output file, format, assessment mode, generated exercises, MCQs, warnings, lint results, and render status.

## Realistic installed example

    library(tutorizeR)

    example_dir <- system.file("examples", "example_course_module", package = "tutorizeR")
    work_dir <- file.path(tempdir(), "tutorizeR-example")
    dir.create(work_dir, recursive = TRUE, showWarnings = FALSE)

    file.copy(file.path(example_dir, "lesson-source.qmd"), work_dir, overwrite = TRUE)
    file.copy(file.path(example_dir, "student_activity.csv"), work_dir, overwrite = TRUE)

    question_bank <- load_question_bank(file.path(example_dir, "question-bank"))

    report <- tutorize(
      input = file.path(work_dir, "lesson-source.qmd"),
      output_dir = work_dir,
      format = "learnr",
      assessment = "both",
      question_bank = question_bank,
      mcq_source = "mixed",
      overwrite = TRUE,
      verbose = FALSE
    )

    print(report)

## Batch conversion

    library(tutorizeR)

    course_dir <- file.path(tempdir(), "course_material")
    output_dir <- file.path(course_dir, "tutorials")

    folder_report <- convert_folder(
      dir = course_dir,
      recursive = TRUE,
      output_dir = output_dir,
      format = "learnr",
      assessment = "both",
      overwrite = TRUE
    )

    print(folder_report)

## Source annotation tags

Use comments inside R chunks:

- `# tutorizeR: skip`
- `# tutorizeR: exercise-only`
- `# tutorizeR: solution-only`
- `# tutorizeR: mcq`
- `# tutorizeR: narrative-only`
- `# tutorizeR: locked`
- `# tutorizeR: hints=Hint 1|Hint 2`

## Limits

Generated tutorials should be reviewed before release. The package can scaffold exercises, solutions, MCQs, and reports, but it does not decide whether a prompt is pedagogically appropriate for a course. Formal learning-outcome evaluation: Not verifiable from repository contents.

## Reproducibility checklist

    library(tutorizeR)

    example_dir <- system.file("examples", "example_course_module", package = "tutorizeR")
    source(file.path(example_dir, "run-example.R"))