quartify

Transform your R scripts into Quarto documentation

Damien Dotta

📦 What is quartify?

An R package that automatically converts your R scripts into Quarto documents (.qmd)

💡 The idea: Generate HTML documentation from commented R scripts

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

🤔 The problem

  • 📝 R scripts with useful comments but hard to read
  • 👥 Difficult to share with non-developers
  • 📊 Complex analyses poorly documented
  • 🔄 Duplication between code and documentation
  • ⏰ Time wasted manually creating documentation

✨ The quartify solution

  • Automation: R → Quarto conversion in one click
  • Preservation: Structure and comments retained
  • Enhancement: HTML rendering
  • Flexibility: R functions, RStudio addins as Shiny apps, a web version (no installation required)
  • Scalability: From simple scripts to Quarto Books

🎯 Why Quarto?

  • 🚀 Official successor to R Markdown (new syntax and features)
  • 🎨 25 themes ready to use
  • 📐 Diagrams: Built-in Mermaid (flowcharts, sequences…)
  • 📱 Responsive: Adapts to all screens
  • 🔮 Future-proof: Active development and growing community

🎯 Use cases

1. Technical documentation

  • 📝 Transform R scripts → Navigable HTML documentation
  • 🔍 Easier code reviews for teams
  • 👥 Share analyses between peers

🎯 Use cases

2. Project management

  • 📚 Create Quarto Books for complex projects
  • 🗂️ Centralized and navigable documentation
  • 🔄 CI/CD integration for up-to-date docs

🚀 Main features

  • 📝 R → Quarto conversion: Scripts to .qmd
  • 🗂️ RStudio Sections: Automatic recognition
  • 💬 Preserved comments: Text in the final document
  • 🔢 Line numbers: Access to line numbers in the original R script
  • 📊 Static code blocks
  • 📑 Table of contents: Automatic
  • 🎨 Customizable YAML: Title, author, theme, options

🚀 Main features (continued)

  • 🌐 HTML rendering: Optional with automatic opening
  • 🎭 25 Quarto themes: Visual customization
  • 🎨 Callouts: Notes, tips, warnings…
  • 📑 Tabsets: Organization in tabs
  • 📊 Mermaid Diagrams: Flowcharts, sequences…
  • 🔍 Code quality: styler/lintr integration

🚀 Main features (continued)

  • 📂 Batch conversion: Entire directories
  • 🔧 RStudio Add-in: IDE integration
  • 🖥️ Shiny interface: usable from any IDE
  • 🌐 Web version: No installation required
  • 📚 Quarto Books: Directories to navigable books
  • 🤖 Automation: CI/CD compatible

🛠️ Installation

From GitHub (development version)

# Install devtools if necessary
install.packages("devtools")

# Install quartify
devtools::install_github("ddotta/quartify")

# Load the package
library(quartify)

🛠️ Installation (continued)

From CRAN (when available)

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

Note

Currently in development - use GitHub

🌐 Web Version - No installation required!

🚀 Try it now!

https://quartify.lab.sspcloud.fr/

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

🌐 Web version features

  1. File upload: One or multiple R scripts
  2. Directory conversion: Select an entire folder
  3. Book creation: Automatic generation of Quarto books
  4. Configuration: Title, author, theme, rendering options
  5. Download: .qmd, .html, or complete .zip archive

🌐 Web version advantages

  • Accessible: From any browser
  • Fast: No local setup required
  • Shareable: Send the link to your colleagues
  • Up-to-date: Always the latest version
  • Risk-free: No installation on your machine
  • Demo: Perfect for testing before installation

💻 Three ways to use quartify

1️⃣ Shiny Interface

library(quartify)
quartify_app()  # Launch the application in the browser

Target audience: Users who prefer a graphical interface and use an IDE other than RStudio

💻 Three ways to use quartify

2️⃣ RStudio Add-in

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

Target audience: Users who prefer a graphical interface and integrated workflow in RStudio

💻 Three ways to use quartify

3️⃣ Command line (CLI)

library(quartify)
rtoqmd("my_script.R", "output.qmd")

Ideal for: Scripts, CI/CD automation…

💻 Shiny Interface - Details

“Convert a file” tab

  • 📁 Select R source file
  • 📝 Configure output name
  • ⚙️ Options: title, author, format, theme
  • 🎨 Choose theme from 25+ available
  • 🔧 Advanced options: numbering, table of contents
  • 📊 Rendering options: HTML, auto-open

💻 Shiny Interface - Details (continued)

“Convert a directory” tab

  • 📂 Select a directory of scripts
  • 📚 “Create a Quarto Book” option (default)
  • 🗂️ Configure output directory
  • ⚙️ Common options: author, theme, rendering
  • 🌐 Optional HTML generation for all files

💻 Shiny Interface - Details (continued)

“Convert multiple files” tab

  • 📁 Upload multiple R files at once
  • 📦 Batch processing
  • 📚 “Create a Quarto Book” option
  • 💾 Download a complete ZIP archive
  • ⚙️ Unified configuration for all files

🔧 Main function: rtoqmd()

Basic syntax

rtoqmd(
  input_file,           # R source file
  output_file = NULL,   # Output .qmd file (auto if NULL)
  title = NULL,         # Document title
  author = NULL,        # Author
  format = "html",      # Output format
  theme = "cosmo",      # Quarto theme
  render = TRUE,        # Generate HTML?
  open_html = TRUE      # Open HTML automatically?
)

🔧 rtoqmd() parameters

Basic parameters

  • input_file: Path to R source script
  • output_file: .qmd file name (default: same name)
  • title: Title in YAML header (otherwise from metadata or filename)
  • author: Author (otherwise from metadata)
  • format: currently only “html”

🔧 rtoqmd() parameters (continued)

Customization parameters

  • theme: Among 25 Quarto themes (default: “cosmo”)
  • number_sections: Number sections? (default: FALSE)
  • show_source_line: Display original line numbers in code chunks (default: TRUE)
  • toc: Include table of contents? (default: TRUE)
  • toc_title: TOC title (default: “Contents”)
  • toc_depth: TOC depth (default: 3)

🔧 rtoqmd() parameters (continued)

Output parameters

  • render: Generate HTML? (default: TRUE)
  • output_html_file: Output HTML filename
  • open_html: Open HTML? (default: TRUE)
  • use_styler: Display formatting suggestions (default: FALSE)
  • use_lintr: Display quality issues (default: FALSE)
  • ⚠ apply_styler: Apply formatting (default: FALSE)

💻 Usage examples

Example 1: Simple conversion

# Basic conversion with HTML rendering
rtoqmd("analysis.R")

# Generates: analysis.qmd + analysis.html
# Opens HTML in browser

💻 Usage examples

Example 2: Without HTML rendering

# Generate only the .qmd
rtoqmd("analysis.R", 
       render = FALSE)

# Generates: analysis.qmd only

💻 Usage examples

Example 3: Full customization

rtoqmd(
  input_file = "my_script.R",
  output_file = "detailed_report.qmd",
  title = "Statistical Analysis of 2024 Sales",
  author = "Data Science Team",
  format = "html",
  theme = "flatly",
  number_sections = TRUE,
  render = TRUE,
  output_html_file = "docs/sales_report_2024.html",
  open_html = TRUE
)

💻 Usage examples

Example 4: With quality check

rtoqmd(
  input_file = "analysis.R",
  output_file = "analysis.qmd",
  use_styler = TRUE,    # Display style suggestions
  use_lintr = TRUE,     # Display quality issues
  render = TRUE
)

# Generates tabsets with:
# - Original code
# - Formatted code (suggestion)
# - Quality issues

📂 Directory conversion: rtoqmd_dir()

Syntax

rtoqmd_dir(
  input_dir,              # Directory containing .R files
  output_dir = NULL,      # Output directory (default: input_dir)
  create_book = TRUE,     # Create a Quarto Book?
  author = NULL,
  render = TRUE,
  output_html_dir = NULL,
  exclude_pattern = NULL  # Pattern to exclude files
)

📂 Directory conversion examples

Example 1: Simple directory conversion

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

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

📂 Directory conversion examples

Example 2: Without creating a Book

# Just convert files individually
rtoqmd_dir("scripts/", 
           create_book = FALSE)

# Generates a .qmd and .html for each .R
# No book structure

📂 Directory conversion examples

Example 3: With file exclusion

# Exclude test files
rtoqmd_dir(
  input_dir = "scripts/",
  exclude_pattern = "^test_.*\\.R$", 
  author = "Data Team",
  theme = "darkly"
)

# All R files whose name starts with test_ will be ignored

📂 Batch conversion examples

Example 4: Custom organization

# Output to a dedicated directory
rtoqmd_dir(
  input_dir = "R/analyses/",
  output_dir = "documentation/",
  output_html_dir = "docs/html/",
  create_book = TRUE,
  author = "My team",
  theme = "cosmo",
  render = TRUE
)

📚 Quarto Books - What are they?

  • Link to documentation
  • 📖 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
  • 🎨 Customizable: Themes, logo, favicon
  • 🌐 Easy publishing: GitLab/GitHub Pages, Netlify, Quarto Pub…

📚 Quarto Book structure

_book/
├── _quarto.yml          # Book configuration
├── index.qmd            # Home page
├── chapter1.qmd         # Chapter 1
├── chapter2.qmd         # Chapter 2
└── ...

quartify automatically generates this structure from your R scripts!

📚 Automatic Book creation

# Active by default with rtoqmd_dir()
rtoqmd_dir("scripts/")

# Generates:
# - _quarto.yml with configuration
# - index.qmd as home page
# - One chapter per R script
# - Navigation in sidebar

📚 Generated _quarto.yml content

project:
  type: book
  output-dir: _book

book:
  title: "Documentation"
  author: "Your name"
  chapters:
    - index.qmd
    - chapter1.qmd
    - chapter2.qmd

format:
  html:
    theme: cosmo

📚 Quarto Books advantages

  • 🎯 Clear organization: Structure complex projects
  • 📖 Smooth navigation: Between all chapters
  • 🔍 Global search: Across all content
  • 📱 Optimal experience: Reading on all devices

📝 R source script format

# Title: Analysis title
#
# Author: Your name
#
# Date: 2025-12-10
#
# Description: Detailed description
# of what this script does
#

## Main section ####

# Explanatory comment

code_r <- "example"

📝 Metadata (optional)

At the beginning of the script

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

Note

If absent, quartify uses the filename as title

📝 Sections and subsections

RStudio syntax

## Level 2 title (Heading 2) ####

### Level 3 title (Heading 3) ====

#### Level 4 title (Heading 4) ----

Important

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

📝 Section hierarchy

# Level 1 title (YAML document title)

## Data import ####

### CSV reading ====

#### Quality check ----

## Exploratory analysis ####

### Descriptive statistics ====

📝 Comments → Text

Basic rule

# This comment alone on its line
# becomes text in the Quarto document

iris |> filter(Species == "setosa")

Becomes in the .qmd:

This comment alone on its line
becomes text in the Quarto document

```{.r}
Line 4
iris |> filter(Species == "setosa")
```

📝 Inline comments (in code)

iris |> 
  # This comment with space before stays in code
  filter(Species == "setosa") |>
  select(Sepal.Length)  # End-of-line comment also stays

Warning

Comments preceded by space or at end of line stay in the code block!

📝 Conversion examples

R script

## Descriptive analysis ####

# Calculate basic statistics

summary(iris)

# The summary() function provides:
# - Minimum and maximum
# - Quartiles
# - Mean

### Species distribution ====

table(iris$Species)

📝 Generated Quarto document

## Descriptive analysis

Calculate basic statistics

```{.r}
Line 5
summary(iris)
```

The summary() function provides:
- Minimum and maximum
- Quartiles
- Mean

### Species distribution

```{.r}
Line 14
table(iris$Species)
```

RStudio Snippets

Install useful code snippets for faster R script writing with install_quartify_snippets().

After installation and RStudio restart, you can use:

  • header + Tab: Insert a document metadata template
  • callout + Tab: Insert a callout template
  • mermaid + Tab: Insert a Mermaid diagram template
  • tabset + Tab: Insert a tabset template

🎨 Callouts - What are they?

Note

Highlighted text blocks to draw attention

Tip

Advice and best practices

Warning

Important points requiring vigilance

🎨 Callouts syntax

In the R script

# callout-note - Callout title
# Callout content over multiple lines.
# Each line starts with #
# 
# Can include paragraphs.

code_after_callout <- "example"

🎨 Callout types

5 available types

# callout-note - General information
# callout-tip - Advice, tip
# callout-warning - Attention required
# callout-caution - Caution needed
# callout-important - Crucial point

🎨 Callout example

R script

## Data loading ####

# callout-important - Prerequisites
# Make sure you have installed the readr package:
# install.packages("readr")

library(readr)
data <- read_csv("file.csv")

🎨 Callout rendering

Prerequisites

Make sure you have installed the readr package:
install.packages("readr")

library(readr)
data <- read_csv("file.csv")

📊 Mermaid Diagrams

What is Mermaid?

  • 📐 Diagram language: Simple Markdown-like syntax
  • 🎨 Automatic rendering: Generated during Quarto rendering
  • 🔄 Natively integrated: No extension required
  • 📊 Multiple types: Flowcharts, sequences, Gantt, classes…

📊 Mermaid syntax in quartify

In the R script

#| mermaid
#| eval: true
flowchart TD
    A[Start] --> B[Processing]
    B --> C{Decision}
    C -->|Yes| D[End]
    C -->|No| B

Note

Use #| tags for chunk options

📊 Mermaid diagram types

Flowchart

#| mermaid
#| eval: true
flowchart LR
    A[Raw data] --> B[Cleaning]
    B --> C[Analysis]
    C --> D[Visualization]
    D --> E[Report]

📊 Mermaid diagram types

Sequence diagram

#| mermaid
#| eval: true
sequenceDiagram
    User->>API: Request
    API->>Database: Query
    Database-->>API: Results
    API-->>User: Response

📊 Mermaid diagram types

Class diagram

#| mermaid
#| eval: true
classDiagram
    class Animal {
        +String name
        +int age
        +eat()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

📊 Mermaid diagram types

Gantt (planning)

#| 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

📑 Tabsets - Organization in tabs

What are they?

  • Link to documentation
  • 📑 Interactive tabs: Organize content
  • 👆 Clickable: User chooses what to see
  • 🎯 Space saving: Avoid too much scrolling
  • 📊 Comparison: Display different views

📑 Tabsets syntax

In the R script

# tabset

# tab - Tab 1
# Description of first tab

code_tab1 <- "example"

# tab - Tab 2
# Description of second tab

code_tab2 <- "another example"

📑 Tabset example

R script

## Data exploration ####

# tabset

# tab - Summary
# Descriptive statistics

summary(iris)

# tab - Structure
# Dataset structure

str(iris)

# tab - Preview
# First rows

head(iris)

📑 Tabset rendering

🔍 Code quality - styler

What is styler?

  • ✨ Automatic formatting: Follows the tidyverse style guide
  • 🎯 Consistency: Uniform code throughout the project
  • 📏 Readability: Indentation, spaces, line breaks
  • 🔧 Integrated in quartify: Display or apply formatting

🔍 Using styler

Option 1: Display suggestions

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

# Generates a tabset with:
# - "Original code": Your code
# - "Formatted code": Styled version

Note

Does NOT apply modifications, just a suggestion

🔍 Using styler

Option 2: Apply directly

rtoqmd("script.R", 
       apply_styler = TRUE)

⚠️ Warning!

Modifies the R source file directly. Make a backup!

🔍 styler formatting example

Before (original)

x=1+2
if(x>0){
print("positive")}
df<-data.frame(a=1:3,b=4:6)

After (formatted)

x <- 1 + 2
if (x > 0) {
  print("positive")
}
df <- data.frame(a = 1:3, b = 4:6)

🔍 Code quality - lintr

What is lintr?

  • 🔍 Static analysis: Detects potential problems
  • ⚠️ Warnings: Syntax, style, potential errors
  • 📊 Best practices: Recommended R conventions
  • 🔧 Integrated in quartify: Displays issues in a tabset

🔍 Using lintr

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

# Generates a tabset with:
# - "Original code": Your code
# - "Issues": List of detected problems

🔍 Combining styler + lintr

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

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

Tip

Perfect for code review!

🔍 Types of problems detected by lintr

  • 🚫 Syntax: Code errors
  • 📏 Line length: > 80 characters
  • 🔤 Naming: Naming conventions
  • ⚠️ Unused variables
  • 🔄 Duplicated code
  • 📦 Packages: Missing dependencies
  • 🎨 Style: Indentation, spaces…

✏️ Using apply_styler

  • ⚠️ The apply_styler parameter allows you to permanently format your R script files according to the tidyverse style guide.
  • The apply_styler parameter only works if use_styler = TRUE.
  • If you set apply_styler = TRUE but use_styler = FALSE, you will receive a warning and the source file will not be modified.
  • The source file is modified BEFORE conversion
  • The formatted file is then used for conversion to .qmd

styler and lintr rendering

🎨 Available Quarto themes

Light themes (19)

cosmo, flatly, journal, litera, lumen, lux, materia, minty, morph, pulse, quartz, sandstone, simplex, sketchy, spacelab, united, vapor, yeti, zephyr

Dark themes (6)

darkly, cyborg, slate, solar, superhero, vapor

🎨 Choosing a theme

With the interface

  • Dropdown menu with preview
  • Real-time preview

From command line

rtoqmd("script.R", theme = "flatly")

🎨 Theme examples

“cosmo” theme (default)

  • 🎨 Modern and clean design
  • 📱 Very responsive
  • 🔵 Professional blue palette

“darkly” theme

  • 🌙 Dark background (dark mode)
  • 👁️ Comfortable for the eyes
  • 💻 Appreciated by developers

🔄 CI/CD Integration

Why automate?

  • 📅 Always up-to-date documentation: With every commit
  • 🤖 No forgetting: Automatic
  • 👥 Collaboration: Whole team benefits
  • 🚀 Deployment: Auto-publishing to GitLab/GitHub Pages for example

🔄 GitLab CI - Configuration

File .gitlab-ci.yml

generate-docs:
  image: rocker/r-ver:4.5.1
  stage: build
  before_script:
    - R -e "install.packages('devtools')"
    - R -e "devtools::install_github('ddotta/quartify')"
  script:
    - R -e "quartify::rtoqmd_dir('scripts/', 
            render = TRUE)"
  artifacts:
    paths:
      - scripts/**/*.qmd
      - scripts/**/*.html

🔄 GitHub Actions - Configuration

File .github/workflows/quartify.yml

name: Generate Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  generate-docs:
    runs-on: ubuntu-latest

🔄 GitHub Actions - Continued

    steps:
      - uses: actions/checkout@v4
      
      - uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.5.1'
      
      - name: Install quartify
        run: |
          install.packages("devtools")
          devtools::install_github("ddotta/quartify")
        shell: Rscript {0}

🔄 GitHub Actions - Generation

      - name: Generate documentation
        run: |
          library(quartify)
          rtoqmd_dir("scripts/", 
                     render = TRUE,
                     author = "Data Team")
        shell: Rscript {0}
      
      - uses: actions/upload-artifact@v4
        with:
          name: documentation
          path: |
            scripts/**/*.qmd
            scripts/**/*.html

💡 Best practices

1. Code structure

  • ✅ Use RStudio sections (####, ====, ----)
  • ✅ Logical hierarchy: Level 2 → 3 → 4
  • ✅ Explicit names: “Import data” > “Import”
  • ✅ Granularity: Not too many sections, not too few

💡 Best practices

2. Comments

  • One idea = one #: No ## in text comments
  • Complete sentences: Capital letters, punctuation
  • Context: Explain the “why,” not the “what” in comments

💡 Best practices

3. Organization

  • ✅ Metadata at the beginning: Title, Author, Date, Description
  • ✅ Logical sections: Introduction → Analysis → Conclusion
  • ✅ Callouts for key points: Important highlights
  • ✅ Tabsets for comparisons: Different approaches

💡 Best practices

4. Quality

  • ✅ Style regularly: Consistent code
  • ✅ Lintr before commit: No surprises
  • ✅ Test rendering: Check generated HTML
  • ✅ Choose a suitable theme: Target audience

💡 Best practices

5. Workflow

  • ✅ Version .qmd: Track changes
  • ✅ CI/CD: Auto documentation
  • ✅ Quarto Books: Multi-file projects

🔗 Resources and documentation (continued)

Guides and tutorials

🙏 Thank you!

Questions?

📧 GitHub Issues for questions/bugs
🌟 Star the project on GitHub!
🤝 Contributions welcome