DEV Community

Cover image for Quartify: Transform Your R Scripts into Quarto Documentation in One Click
Damien Dotta
Damien Dotta

Posted on

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

#rstats #documentation #r #datascience

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 ----
Enter fullscreen mode Exit fullscreen mode

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

Hierarchy Example 

## Data Import ####

### Read CSV ====

#### Quality Check ----

## Exploratory Analysis ####

### Descriptive Statistics ====
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

From GitHub (development version) 

install.packages("devtools")
devtools::install_github("ddotta/quartify")
library(quartify)
Enter fullscreen mode Exit fullscreen mode

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()
Enter fullscreen mode Exit fullscreen mode

Ideal for users who prefer a graphical interface.

2. RStudio Add-in

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

Perfect for an integrated RStudio workflow.

3. Command Line 

library(quartify)
rtoqmd("my_script.R")
Enter fullscreen mode Exit fullscreen mode

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"
  )
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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
)
Enter fullscreen mode Exit fullscreen mode

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
)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 #
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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
#
Enter fullscreen mode Exit fullscreen mode

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)
}
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

RStudio Snippets 

install_quartify_snippets()
Enter fullscreen mode Exit fullscreen mode

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 ####
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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.
#
Enter fullscreen mode Exit fullscreen mode

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

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)
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)