mariner

mariner turns one parameterized Quarto template into a set of reports, renders them, and bundles each one into a zip archive. It carries its own Quarto PDF theme: typography, brand colours, and matching ggplot2 scales.

Documentation: https://thomasqmd.github.io/mariner/.

Installation

mariner installs from GitHub, so R builds it from source.

Windows needs Rtools first. Match the version to your R — check R.version.string, so R 4.5.x takes Rtools45 — then restart RStudio. Without it the install stops at Could not find tools necessary to compile a package. macOS and Linux need nothing extra.

# install.packages("pak")
pak::pak("thomasqmd/mariner", dependencies = TRUE)

dependencies = TRUE brings the Suggests along — tidyverse, patchwork, tinytex and the rest — which is what a course usually wants. Leave it off to install only what mariner itself needs.

Folder Structure

mariner works in three project directories:

your-project/
├── assets/          # the Quarto theme, assembled once
├── reports/         # the .qmd sources, their PDFs, and _extensions/
└── zip_files/       # one archive per report: PDF, source, R script

Quickstart

library(mariner)

# 1. Create the folders, install the Quarto theme, set the author
mariner_setup_project(author = "Alice Smith")

# 2. One row per report; only what varies between them belongs here
report_params <- expand.grid(
  chapter = 1,
  problem_numbers = 1:2,
  stringsAsFactors = FALSE
)

# 3. Write the .qmd files into reports/
qmd_files <- generate_reports(report_params)

# 4. Render and bundle into zip_files/
zip_files <- process_files(qmd_files)

Every column that varies has to appear in the file name template, which defaults to "Report-{chapter}_{problem_numbers}". Otherwise two rows resolve to one name and the second overwrites the first.

The author is not a column. The setup call above writes it to _mariner.yml, and from there it fills the template’s author parameter for every report in the project: one person runs the batch, and it is their name on all of it. A params_df column of the same name still wins, for the batch whose author does vary.

Theming

theme_mariner() and the scale_*_mariner_*() families draw a figure in the same colours as the page:

library(ggplot2)

ggplot(mpg, aes(class, hwy, color = class)) +
  geom_jitter(width = 0.2, height = 0, size = 2) +
  scale_colour_mariner_d() +
  labs(
    title = "Fuel Economy by Vehicle Class",
    x = "Vehicle Class",
    y = "Highway MPG"
  ) +
  theme_mariner() +
  theme(legend.position = "none")

If It Does Not Work

mariner_check_setup() reports on Quarto, LaTeX, the fonts, the folders and the theme, and prints the fix for anything missing:

mariner_check_setup()

If the fonts are missing:

mariner_install_fonts()