| Type: | Package |
| Title: | Convert R Markdown or Quarto Content into Interactive Tutorials |
| Version: | 0.4.5 |
| Author: | Aurélien Nicosia [aut, cre] |
| Maintainer: | Aurélien Nicosia <aurelien.nicosia@mat.ulaval.ca> |
| Description: | Helps teachers convert existing '.Rmd' and '.qmd' teaching material into interactive tutorials for 'learnr' or 'quarto-live'. Conversion preserves narrative text, setup chunks, and major chunk options, supports teacher tags, and provides explicit validation and conversion reports. Output conventions follow 'learnr' as described by Aden-Buie et al. (2025) <doi:10.32614/CRAN.package.learnr>, 'quarto-live' as described by Stagg (2024) https://tidyverse.org/blog/2024/10/quarto-live-0-1-1/, and R Markdown as described by Xie, Allaire and Grolemund (2018, ISBN:9781138359338). |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.3 |
| Depends: | R (≥ 4.0) |
| Imports: | cli, jsonlite, lifecycle, rlang, rmarkdown, rstudioapi, yaml |
| Suggests: | commonmark, covr, dplyr, ggplot2, knitr, learnr, lintr, miniUI, readr, shiny, testthat (≥ 3.0.0) |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| URL: | https://github.com/AurelienNicosiaULaval/tutorizeR |
| BugReports: | https://github.com/AurelienNicosiaULaval/tutorizeR/issues |
| NeedsCompilation: | no |
| Packaged: | 2026-06-05 15:26:09 UTC; aureliennicosia |
| Repository: | CRAN |
| Date/Publication: | 2026-06-11 11:40:02 UTC |
Build callout-style MCQ lines
Description
Build callout-style MCQ lines
Usage
build_callout_question_lines(question, answers, language = "en")
Build normalized chunk block object
Description
Build normalized chunk block object
Usage
build_chunk_block(
spec,
body_lines,
fence,
raw_lines,
inline = FALSE,
start_line = NA_integer_,
end_line = NA_integer_
)
Build default setup chunk when none is present
Description
Build default setup chunk when none is present
Usage
build_default_setup_chunk(language, seed = NULL)
Build generic engine chunk header
Description
Build generic engine chunk header
Usage
build_engine_chunk_header(engine, label = NULL, options = character())
Build exercise lines from source R chunk
Description
Build exercise lines from source R chunk
Usage
build_exercise_lines(format, exercise_label, source_chunk, language, tags)
Build learnr::question chunk lines
Description
Build learnr::question chunk lines
Usage
build_learnr_question_lines(question, answers, label, allow_retry = TRUE)
Build MCQ lines according to selected mode
Description
Build MCQ lines according to selected mode
Usage
build_mcq_for_chunk_mode(
source_chunk,
format,
mcq_label_base,
registry,
language,
question_bank,
mcq_source,
index
)
Build YAML header lines for target format
Description
Build YAML header lines for target format
Usage
build_output_yaml(source_yaml, format, language = "en")
Build placeholder MCQ for chunk-level MCQ generation
Description
Build placeholder MCQ for chunk-level MCQ generation
Usage
build_placeholder_mcq(format, mcq_label, source_chunk, language)
Build knitr R chunk header
Description
Build knitr R chunk header
Usage
build_r_chunk_header(label = NULL, options = character())
Build solution lines from source R chunk
Description
Build solution lines from source R chunk
Usage
build_solution_lines(format, solution_label, source_chunk, language)
Build converted tutorial lines from parsed document blocks
Description
Build converted tutorial lines from parsed document blocks
Usage
build_tutorial_lines(
parsed,
format,
assessment,
language = "en",
seed = NULL,
question_bank = NULL,
mcq_source = c("inline", "bank", "mixed")
)
Render a generated tutorial and return render status
Description
Render a generated tutorial and return render status
Usage
check_tutorial(file, language = c("en", "fr"))
Arguments
file |
Path to tutorial '.Rmd' to render. |
language |
Message language ('"en"' or '"fr"'). |
Value
Invisibly, the render output path or the error object.
Examples
if (interactive()) {
check_tutorial("analysis-tutorial.Rmd")
}
Render check implementation for generated learnr tutorials
Description
Render check implementation for generated learnr tutorials
Usage
check_tutorial_render(file, language = "en")
Convert all '.Rmd'/'.qmd' files in a folder
Description
Converts every matching source file in 'dir', with resilient per-file error handling and a summary report.
Usage
convert_folder(
dir = ".",
pattern = "\\.(Rmd|qmd)$",
recursive = FALSE,
output_dir = NULL,
format = c("learnr", "quarto-live"),
assessment = c("code", "mcq", "both"),
overwrite = FALSE,
language = c("en", "fr"),
seed = NULL,
verbose = TRUE,
question_bank = NULL,
mcq_source = c("inline", "bank", "mixed"),
lint_strict = FALSE
)
Arguments
dir |
Folder containing source files. |
pattern |
Regex pattern used to select files. |
recursive |
Logical; recurse into subdirectories? |
output_dir |
Output directory for generated files. |
format |
Output format ('"learnr"' or '"quarto-live"'). |
assessment |
Assessment mode ('"code"', '"mcq"', '"both"'). |
overwrite |
Logical; overwrite existing outputs? |
language |
Message/template language ('"en"' or '"fr"'). |
seed |
Optional integer seed injected in setup chunk. |
verbose |
Logical; print progress and summary? |
question_bank |
Optional path(s) or 'tutorize_question_bank' object. |
mcq_source |
MCQ generation source ('"inline"', '"bank"', '"mixed"'). |
lint_strict |
Logical; fail conversion when lint reports errors. |
Value
A 'tutorize_folder_report' object (invisibly).
Examples
labs <- file.path(tempdir(), "labs")
out <- file.path(tempdir(), "tutorials")
dir.create(labs, recursive = TRUE, showWarnings = FALSE)
writeLines(
c("---", "title: Demo", "---", "", "```{r}", "1 + 1", "```"),
file.path(labs, "demo.Rmd")
)
report <- convert_folder(labs, output_dir = out, recursive = TRUE, verbose = FALSE)
print(report)
Backward-compatible wrapper for tutorial conversion
Description
'convert_to_tutorial()' is kept for compatibility with earlier versions. New code should use [tutorize()].
Usage
convert_to_tutorial(
input_file,
output_file = NULL,
assessment = c("code", "mcq", "both"),
format = c("learnr", "quarto-live"),
add_mcq = NULL,
question_bank = NULL,
mcq_source = c("inline", "bank", "mixed"),
lint_strict = FALSE
)
Arguments
input_file |
Path to source '.Rmd' or '.qmd' file. |
output_file |
Output path. |
assessment |
Assessment mode: '"code"', '"mcq"', or '"both"'. |
format |
Output format: '"learnr"' or '"quarto-live"'. |
add_mcq |
Deprecated. Use 'assessment' instead. |
question_bank |
Optional path(s) or 'tutorize_question_bank' object. |
mcq_source |
MCQ generation source: '"inline"', '"bank"', '"mixed"'. |
lint_strict |
Logical; fail conversion when lint reports errors. |
Value
Invisibly, the generated output file path.
Examples
input <- tempfile(fileext = ".Rmd")
output <- tempfile(fileext = ".Rmd")
writeLines(c("---", "title: Demo", "---", "", "```{r}", "1 + 1", "```"), input)
convert_to_tutorial(input, output_file = output)
Count generated MCQ blocks in already rendered lines
Description
Count generated MCQ blocks in already rendered lines
Usage
count_generated_mcq(lines, format)
Decide effective conversion mode for one source chunk
Description
Decide effective conversion mode for one source chunk
Usage
derive_assessment_mode(assessment, tags)
Derive LMS items from parsed chunks
Description
Derive LMS items from parsed chunks
Usage
derive_manifest_items(blocks, include_solutions = TRUE)
Detect conflicting tag combinations
Description
Detect conflicting tag combinations
Usage
detect_tag_conflict(tags)
Detect unknown tutorizeR tags from comment lines
Description
Detect unknown tutorizeR tags from comment lines
Usage
detect_unknown_tags(lines)
Drop option tokens by key name
Description
Drop option tokens by key name
Usage
drop_options(option_tokens, keys)
Build an empty lint findings table
Description
Build an empty lint findings table
Usage
empty_findings()
Estimate expected completion time in minutes
Description
Estimate expected completion time in minutes
Usage
estimate_completion_minutes(stats)
Export a profile-aware LMS manifest
Description
Export a profile-aware LMS manifest
Usage
export_lms_manifest(
input,
output_file = NULL,
profile = c("generic", "canvas", "moodle"),
include_solutions = TRUE,
language = c("en", "fr")
)
Arguments
input |
Source '.Rmd'/'.qmd' file. |
output_file |
Output path for the manifest file. |
profile |
Manifest profile ('"generic"', '"canvas"', '"moodle"'). |
include_solutions |
Logical; mark exercise solutions as available. |
language |
Manifest language ('"en"' or '"fr"'). |
Value
A 'tutorize_lms_manifest' object.
Export a tutorial-ready package scaffold (opt-in)
Description
Export a tutorial-ready package scaffold (opt-in)
Usage
export_tutorial_package(
input,
path = NULL,
package_name = NULL,
overwrite = FALSE
)
Arguments
input |
Source '.Rmd'/'.qmd' file. |
path |
Parent directory where the package directory will be created. |
package_name |
Optional package name. Derived from input by default. |
overwrite |
Logical; replace existing package directory if present. |
Value
Invisibly returns the created package path.
Extract markdown heading titles from parsed blocks
Description
Extract markdown heading titles from parsed blocks
Usage
extract_section_titles(blocks)
Locate an i18n YAML file for the given language
Description
Locate an i18n YAML file for the given language
Usage
find_i18n_file(language)
Build a simple line diff between source and output
Description
Build a simple line diff between source and output
Usage
generate_simple_diff(source_lines, output_lines)
Load i18n dictionary from YAML with cache
Description
Load i18n dictionary from YAML with cache
Usage
get_i18n_dictionary(language)
Check whether lint report contains blocking errors
Description
Check whether lint report contains blocking errors
Usage
has_lint_errors(report)
Check whether a chunk option already exists
Description
Check whether a chunk option already exists
Usage
has_option(option_tokens, key)
Determine if block is explicit MCQ definition block
Description
Determine if block is explicit MCQ definition block
Usage
is_mcq_block(block)
Determine if block is MCQ reference block
Description
Determine if block is MCQ reference block
Usage
is_mcq_ref_block(block)
Determine if chunk is R engine
Description
Determine if chunk is R engine
Usage
is_r_chunk(block)
Determine if chunk is setup chunk
Description
Determine if chunk is setup chunk
Usage
is_setup_chunk(block)
RStudio Addin: Convert active document to tutorial
Description
Opens a lightweight prompt flow (format, assessment, output directory, overwrite) and converts the currently active file.
Usage
launch_tutorizeR_addin()
Value
Invisibly returns the 'tutorize_report' object, or 'NULL' when cancelled.
RStudio Addin: Convert a folder to tutorials
Description
Prompts for folder and conversion options, then converts all matching files.
Usage
launch_tutorizeR_folder_addin()
Value
Invisibly returns a 'tutorize_folder_report' object, or 'NULL' when cancelled.
RStudio Addin: Preview conversion with lint and diff
Description
Opens a gadget with Source, Output, Diff, Lint and Logs tabs.
Usage
launch_tutorizeR_preview_addin()
Value
Invisibly returns a 'tutorize_report' object or 'NULL'.
Build a lint finding row
Description
Build a lint finding row
Usage
lint_row(code, severity, message, line = NA_integer_, chunk_label = "")
Lint source pedagogical constraints before conversion
Description
Lint source pedagogical constraints before conversion
Usage
lint_source(
input,
question_bank = NULL,
language = c("en", "fr"),
strict = FALSE
)
Arguments
input |
Source '.Rmd' or '.qmd' file. |
question_bank |
Optional 'tutorize_question_bank' object. |
language |
Message language ('"en"' or '"fr"'). |
strict |
Logical; if 'TRUE', stop when lint errors are present. |
Value
A 'tutorize_lint_report' object.
Load a reusable MCQ question bank from YAML/JSON files
Description
Load a reusable MCQ question bank from YAML/JSON files
Usage
load_question_bank(
path,
recursive = TRUE,
format = c("auto", "yaml", "json"),
strict = TRUE,
language = c("en", "fr")
)
Arguments
path |
File or directory path(s) containing question bank files. |
recursive |
Logical; recurse into subdirectories when 'path' is a directory. |
format |
Input format: '"auto"', '"yaml"', or '"json"'. |
strict |
Logical; if 'TRUE', validation errors stop execution. |
language |
Language for validation messages ('"en"' or '"fr"'). |
Value
A 'tutorize_question_bank' object.
Lookup nested translation key in dictionary
Description
Lookup nested translation key in dictionary
Usage
lookup_i18n_key(dict, key)
Register and generate unique deterministic labels
Description
Register and generate unique deterministic labels
Usage
make_unique_label(base, registry)
Build folder conversion report object
Description
Build folder conversion report object
Usage
new_tutorize_folder_report(results)
Construct a lint report object
Description
Construct a lint report object
Usage
new_tutorize_lint_report(source, findings, context = "source")
Build a conversion report object
Description
Build a conversion report object
Usage
new_tutorize_report(
input_file,
output_file,
format,
assessment,
stats,
render_result,
warnings = character(),
lint_report = NULL,
messages = character()
)
Normalize root object to list of question entries
Description
Normalize root object to list of question entries
Usage
normalize_question_entries(raw)
Normalize one question entry to a canonical list
Description
Normalize one question entry to a canonical list
Usage
normalize_question_item(x, source_file = "")
Parse knitr/quarto chunk specification
Description
Parse knitr/quarto chunk specification
Usage
parse_chunk_spec(spec)
Transform source lines into converted tutorial body
Description
Transform source lines into converted tutorial body
Usage
parse_chunks(lines, assessment = "code", format = "learnr")
Parse an input R Markdown / Quarto document into structured blocks
Description
Parse an input R Markdown / Quarto document into structured blocks
Usage
parse_input_document(input_file)
Parse markdown body into text/chunk blocks
Description
Parse markdown body into text/chunk blocks
Usage
parse_markdown_blocks(lines)
Parse YAML from a tutorizeR-mcq-ref block
Description
Parse YAML from a tutorizeR-mcq-ref block
Usage
parse_mcq_ref_yaml(block)
Parse YAML from a tutorizeR-mcq block
Description
Parse YAML from a tutorizeR-mcq block
Usage
parse_mcq_yaml(block)
Parse a single question-bank file
Description
Parse a single question-bank file
Usage
parse_question_bank_file(file)
Parse teacher tags declared in code comments
Description
Parse teacher tags declared in code comments
Usage
parse_tutorizer_tags(lines)
Print method for folder conversion reports
Description
Print method for folder conversion reports
Usage
## S3 method for class 'tutorize_folder_report'
print(x, ...)
Arguments
x |
A 'tutorize_folder_report' object. |
... |
Unused. |
Value
'x', invisibly.
Print method for lint reports
Description
Print method for lint reports
Usage
## S3 method for class 'tutorize_lint_report'
print(x, ...)
Arguments
x |
A 'tutorize_lint_report' object. |
... |
Unused. |
Value
'x', invisibly.
Print method for LMS manifest exports
Description
Print method for LMS manifest exports
Usage
## S3 method for class 'tutorize_lms_manifest'
print(x, ...)
Arguments
x |
A 'tutorize_lms_manifest' object. |
... |
Unused. |
Value
'x', invisibly.
Print method for tutorize conversion reports
Description
Print method for tutorize conversion reports
Usage
## S3 method for class 'tutorize_report'
print(x, ...)
Arguments
x |
A 'tutorize_report' object. |
... |
Unused. |
Value
'x', invisibly.
Register external label without modification
Description
Register external label without modification
Usage
register_label(label, registry)
Resolve effective language for tutorizeR
Description
Resolve effective language for tutorizeR
Usage
resolve_language(language = NULL)
Resolve output file path from user input
Description
Resolve output file path from user input
Usage
resolve_output_file(
input,
format,
output_dir = NULL,
output_file = NULL,
language = "en"
)
Resolve file list for question-bank loading
Description
Resolve file list for question-bank loading
Usage
resolve_question_bank_files(path, recursive = TRUE, format = "auto")
Run conversion preview gadget
Description
Run conversion preview gadget
Usage
run_preview_gadget(input_file)
Sanitize chunk labels to portable deterministic strings
Description
Sanitize chunk labels to portable deterministic strings
Usage
sanitize_label(x)
Select question(s) from a loaded question bank
Description
Select question(s) from a loaded question bank
Usage
select_questions_from_bank(
bank,
ids = NULL,
n = NULL,
strategy = c("ordered", "random"),
tags = NULL,
difficulty = NULL,
language = NULL
)
Split optional YAML front matter from body lines
Description
Split optional YAML front matter from body lines
Usage
split_front_matter(lines)
Split a comma-separated option string while preserving quoted commas
Description
Split a comma-separated option string while preserving quoted commas
Usage
split_option_tokens(x)
Strip teacher tag comments from chunk body
Description
Strip teacher tag comments from chunk body
Usage
strip_tag_lines(lines)
Remove leading YAML front matter lines
Description
Remove leading YAML front matter lines
Usage
strip_yaml(lines)
Translate a tutorizeR message key
Description
Looks up a message key in language dictionaries and interpolates named
placeholders (for example, "{name}").
Usage
tr(key, ..., language = NULL)
Arguments
key |
Dot-separated translation key (e.g. '"messages.render_ok"'). |
... |
Named interpolation values. |
language |
Optional language ('"en"' or '"fr"'). |
Value
A translated character string.
Convert a parsed MCQ block to output lines
Description
Convert a parsed MCQ block to output lines
Usage
transform_mcq_block(block, format, index)
Convert a parsed MCQ reference block to output lines
Description
Convert a parsed MCQ reference block to output lines
Usage
transform_mcq_ref_block(block, format, index, question_bank, language = "en")
Transform existing setup chunk and inject required lines for learnr
Description
Transform existing setup chunk and inject required lines for learnr
Usage
transform_setup_chunk(block, format, language, seed, registry)
Trim trailing blank lines from final output
Description
Trim trailing blank lines from final output
Usage
trim_trailing_blank_lines(lines)
Convert a source document into an interactive tutorial
Description
'tutorize()' is the canonical high-level API. It converts an existing '.Rmd' or '.qmd' source document into a tutorial-ready document for 'learnr' or 'quarto-live'.
Usage
tutorize(
input,
output_dir = NULL,
format = c("learnr", "quarto-live"),
assessment = c("code", "mcq", "both"),
overwrite = FALSE,
language = c("en", "fr"),
seed = NULL,
verbose = TRUE,
output_file = NULL,
question_bank = NULL,
mcq_source = c("inline", "bank", "mixed"),
lint_strict = FALSE
)
Arguments
input |
Path to source '.Rmd' or '.qmd' file. |
output_dir |
Output directory. Required unless 'output_file' is supplied. |
format |
Output format: '"learnr"' (default) or '"quarto-live"'. |
assessment |
Assessment mode: '"code"', '"mcq"', or '"both"'. |
overwrite |
Logical; overwrite existing output file? |
language |
Message/template language: '"en"' (default) or '"fr"'. |
seed |
Optional integer seed injected into setup chunk. |
verbose |
Logical; show progress and diagnostic messages? |
output_file |
Optional explicit output file path. Useful for wrappers. |
question_bank |
Optional path(s) or 'tutorize_question_bank' object. |
mcq_source |
MCQ generation source: '"inline"', '"bank"', '"mixed"'. |
lint_strict |
Logical; fail conversion when lint reports errors. |
Value
A 'tutorize_report' object (invisibly).
Examples
input <- tempfile(fileext = ".qmd")
writeLines(c("---", "title: Demo", "---", "", "```{r}", "1 + 1", "```"), input)
rep <- tutorize(
input,
output_dir = tempdir(),
format = "learnr",
assessment = "both",
overwrite = TRUE,
verbose = FALSE
)
print(rep)
Validate tutorizeR input arguments
Description
Performs defensive checks for file path, format, assessment, and extension.
Usage
validate_input(
input,
format = c("learnr", "quarto-live"),
assessment = c("code", "mcq", "both"),
language = c("en", "fr")
)
Arguments
input |
Path to source '.Rmd' or '.qmd' document. |
format |
Target output format ('"learnr"' or '"quarto-live"'). |
assessment |
Assessment mode ('"code"', '"mcq"', or '"both"'). |
language |
Language for validation messages ('"en"' or '"fr"'). |
Value
Invisibly returns 'TRUE' if validation succeeds.
Run a lightweight markdown parse validation when commonmark is available
Description
Run a lightweight markdown parse validation when commonmark is available
Usage
validate_markdown_structure(lines)
Validate expected MCQ fields
Description
Validate expected MCQ fields
Usage
validate_mcq_definition(definition, index)
Validate expected MCQ ref fields
Description
Validate expected MCQ ref fields
Usage
validate_mcq_ref_definition(definition, language = "en")
Validate output path and overwrite strategy
Description
Validate output path and overwrite strategy
Usage
validate_output(
output_file,
input_file,
overwrite = FALSE,
language = c("en", "fr")
)
Arguments
output_file |
Destination output file path. |
input_file |
Source file path. |
overwrite |
Logical; allow replacing an existing output. |
language |
Language for validation messages ('"en"' or '"fr"'). |
Value
Invisibly returns 'TRUE' if validation succeeds.
Validate a 'tutorize_question_bank' object
Description
Validate a 'tutorize_question_bank' object
Usage
validate_question_bank(bank, strict = TRUE, language = c("en", "fr"))
Arguments
bank |
A question bank object from [load_question_bank()]. |
strict |
Logical; if 'TRUE', stop on validation errors. |
language |
Language for validation messages ('"en"' or '"fr"'). |
Value
A 'tutorize_lint_report' object.
Validate one normalized question item
Description
Validate one normalized question item
Usage
validate_question_item(q, language = "en")
Write a conversion report to JSON or YAML
Description
Write a conversion report to JSON or YAML
Usage
write_tutorize_report(report, file, format = c("json", "yaml"), pretty = TRUE)
Arguments
report |
A 'tutorize_report' object. |
file |
Output file path. |
format |
Output serialization format ('"json"' or '"yaml"'). |
pretty |
Logical; pretty-print JSON output. |
Value
Invisibly returns 'file'.