Quartify: Transform Your R Scripts into Quarto Documentation in One Click

Damien Dotta — Mon, 26 Jan 2026 12:49:10 +0000

Introduction: The Challenge of Code Documentation

How many times have you written a brilliant R analysis, only to face the tedious task of converting it into a well-formatted report? If you're like most R users, you've probably spent hours copying and pasting code into Quarto documents, wrestling with chunk options, and reformatting comments.

What if I told you there's a better way? Enter quartify – an R package that automatically transforms your existing R scripts into polished Quarto documents, without modifying a single line of your original code.

What is quartify?

quartify is an R package that bridges the gap between your analysis scripts and publication-ready documents. It converts R scripts (.R files) into Quarto documents (.qmd files).

The philosophy of quartify: your code stays code, your comments become narrative text. Unlike other tools requiring special syntax, quartify works with your scripts exactly as they are.

Important note: quartify is designed to create static documentation of your R script, not an executable notebook. The code displayed in the Quarto document is not executed: it's a visual representation of your script for documentation and sharing purposes.

The goal: Keep your scripts clean and familiar while making them compatible with the Quarto ecosystem.

The Problem quartify Solves

📝 R scripts with useful comments but hard to read for non-developers
👥 Difficult to share with non-technical colleagues
🔄 Duplication between code and documentation
⏰ Time wasted manually creating documentation

Why quartify Stands Out

1. Frictionless Conversion

Quartify works with regular R scripts. Your comments (#) naturally become narrative text, while your code blocks are intelligently organized.

2. Respects Your Structure with RStudio Sections

This is one of quartify's key features! If you use RStudio code sections, quartify automatically converts them into proper markdown headers.

RStudio Section Syntax

## Heading 2 ####

### Heading 3 ====

#### Heading 4 ----

Important: Minimum 4 symbols at the end (#, = or -)

Hierarchy Example

## Data Import ####

### Read CSV ====

#### Quality Check ----

## Exploratory Analysis ####

### Descriptive Statistics ====

Your navigation structure is preserved without any extra work!

3. From Script to Book in Seconds

Need to convert an entire directory of scripts into a Quarto Book? Quartify handles multiple files easily, automatically assembling them into a coherent, navigable document structure.

Installation

From CRAN

install.packages("quartify")
library(quartify)

From GitHub (development version)

install.packages("devtools")
devtools::install_github("ddotta/quartify")
library(quartify)

Web Version - No Installation Required!

Try quartify immediately without installing anything: https://quartify.lab.sspcloud.fr/

✅ No R installation required
✅ Complete web interface
✅ All features available

Three Ways to Use quartify

1. Shiny Interface

library(quartify)
quartify_app()

Ideal for users who prefer a graphical interface.

2. RStudio Add-in

Open an R script in RStudio
Menu Addins → Convert R Script to Quarto

Perfect for an integrated RStudio workflow.

3. Command Line

library(quartify)
rtoqmd("my_script.R")

Ideal for automation and CI/CD pipelines.

Complete Example

Here's a simple R script analyzing the iris dataset:

# Title : Iris Dataset Analysis
#
# Author : Your name
#
# Date : 2025-12-10
#
# Description : Exploring differences
# between iris species
#

## Data Exploration ####

# Load necessary packages

library(ggplot2)
library(dplyr)

# This classic dataset contains iris flower measurements

data("iris")
summary(iris)

## Visualization ####

# Let's examine the relationship between petal length and width

ggplot(iris, aes(x = Petal.Length, y = Petal.Width, color = Species)) +
  geom_point(size = 3, alpha = 0.7) +
  theme_minimal() +
  labs(
    title = "Iris Petal Dimensions by Species",
    x = "Petal Length (cm)",
    y = "Petal Width (cm)"
  )

## Statistical Analysis ####

# Calculate statistics by species

iris %>%
  group_by(Species) %>%
  summarise(
    mean_petal_length = mean(Petal.Length),
    mean_petal_width = mean(Petal.Width),
    .groups = "drop"
  )

To convert this script:

library(quartify)

# Simple conversion
rtoqmd("iris_analysis.R")

# With immediate HTML rendering
rtoqmd("iris_analysis.R", render_html = TRUE, open_html = TRUE)

Quartify will:

Convert your sections (## Data Exploration ####) into markdown headers
Transform your comments into narrative text
Organize your code into well-structured chunks
Generate an elegant HTML with table of contents

Main Function: rtoqmd()

rtoqmd(
  input_file,               # Source R file
  output_file = NULL,       # Output .qmd file
  title = "My title",       # Document title
  author = "Your name",     # Author
  theme = "cosmo",          # Quarto theme (25+ available)
  render_html = TRUE,       # Generate HTML
  open_html = FALSE,        # Open HTML automatically
  number_sections = TRUE,   # Number sections
  show_source_line = TRUE   # Show original line numbers
)

Directory Conversion: rtoqmd_dir()

rtoqmd_dir(
  input_dir,              # Directory containing .R files
  output_dir = NULL,      # Output directory
  create_book = TRUE,     # Create a Quarto Book
  author = "Your name",   # Author
  render_html = FALSE     # Generate HTML files
)

Example:

# Convert all .R files in a directory to a Quarto Book
rtoqmd_dir("scripts/analyses")

# Generates:
# - One .qmd for each .R
# - A Quarto Book with navigation
# - HTML for each file

Quarto Books

Quarto Books offer:

📖 Book structure: Chapters, parts, navigation
🗂️ Automatic sidebar: Navigation between all files
🔍 Integrated search: Search across the entire book
📱 Responsive design: Adapted for mobile/tablet/desktop

quartify automatically generates this structure from your R scripts!

Advanced Features

Callouts

Highlight important information:

# callout-note - Callout Title
# Callout content on multiple lines.
# Each line starts with #

5 types available: callout-note, callout-tip, callout-warning, callout-caution, callout-important

Tabsets

Organize content in interactive tabs:

## Exploration des données ####

# tabset

# tab - Résumé
# Statistiques descriptives

summary(iris)

# tab - Structure
# Structure du dataset

str(iris)

# tab - Aperçu
# Premières lignes

head(iris)

Mermaid Diagrams

Embed diagrams directly:

#| mermaid
#| eval: true
# gantt
#     title Project planning
#     dateFormat YYYY-MM-DD
#     section Phase 1
#     Data collection :2025-01-01, 30d
#     Cleaning        :2025-01-31, 20d
#     section Phase 2
#     Analysis        :2025-02-20, 30d
#

Functions

#' Additionne deux nombres
#'
#' @param x Une valeur numérique
#' @param y Une valeur numérique
#' @return La somme de x et y
#' @examples
#' add_numbers(2, 3)
#' @export
add_numbers <- function(x, y) {
  return(x + y)
}

Code Quality

Integration with styler and lintr:

rtoqmd("script.R", 
       use_styler = TRUE,
       use_lintr = TRUE)

# Generates a tabset with:
# - "Original code"
# - "Formatted code" (styler suggestion)
# - "Issues" (lintr problems)

Votre navigateur ne supporte pas la lecture de vidéos.

RStudio Snippets

install_quartify_snippets()

After restarting RStudio, use:

header + Tab: Metadata template
callout + Tab: Callout template
mermaid + Tab: Diagram template
tabset + Tab: Tabset template

Best Practices

1. Structure Your Scripts with Sections

## Introduction ####
## Analysis ####
## Results ####
## Conclusions ####

2. Write Narrative Comments

# We use a linear regression to examine
# the relationship between temperature and ice cream sales
model <- lm(sales ~ temperature, data = ice_cream_data)

3. Use Metadata at the Beginning of Your Script

# Title : Iris Data Analysis
#
# Author : Jane Doe
#
# Date : 2025-12-05
#
# Description : This analysis explores the differences
# between the three iris species.
#

Learn more here.

Use Cases

Technical documentation: Transform R scripts into navigable HTML documentation
Code review: Facilitate reviews for teams
Project management: Create Quarto Books for complex projects
Teaching: Transform course scripts into accessible tutorials
Reproducible research: Convert exploratory analyses into publication-ready supplements

Resources

📦 GitHub: github.com/ddotta/quartify
📖 Documentation: ddotta.github.io/quartify
🌐 Web version: quartify.lab.sspcloud.fr
🎓 Getting Started: Getting Started Guide
💻 Presentation:
📚 Quarto docs: quarto.org

Conclusion

Quartify elegantly bridges the gap between exploratory code and polished documentation. It respects your workflow, preserves your structure, and eliminates the tedious reformatting.

The next time you finish an R script and think "I should document this," remember: with quartify, you might have already done so without realizing it.

Try It Now!

install.packages("quartify")
library(quartify)
rtoqmd("your_script.R", render_html = TRUE)

For more information about quartify, visit the GitHub repository. Feel free to contribute or report issues!

This article is shared on R-bloggers:
https://www.r-bloggers.com

DEV Community: Damien Dotta