Getting Started with quartify • quartify

🇫🇷 Version française disponible / French version available

Introduction

quartify is an R package that automatically converts R scripts into Quarto markdown documents (.qmd). The package recognizes RStudio code sections to create properly structured documents with navigation. This vignette will guide you through the basic usage and features of the package.

Comparison with knitr::spin()

If you’re familiar with knitr::spin(), you might wonder how quartify differs:

Feature	knitr::spin()	quartify
Output Format	R Markdown (.Rmd)	Quarto (.qmd)
Text Syntax	`#'` for markdown	`#` (natural R comments)
Modern Features	Limited to R Markdown	Full Quarto capabilities
Callouts	Manual HTML/CSS	Native Quarto callouts
Diagrams	External tools	Native Mermaid support
Themes	Limited R Markdown themes	25+ modern Quarto themes

Why choose quartify?

Modern Quarto Ecosystem: Benefit from Quarto’s next-generation features (callouts, tabsets, etc.)
Cleaner R Scripts: Use natural R commenting without special #' or #+ syntax - your scripts remain readable as standalone R code
Advanced Outputs: Generate websites, books, presentations, and scientific articles with the same workflow
Better Theming: Access to modern, responsive HTML themes with consistent styling
Future-Proof: Quarto is actively developed by Posit as the successor to R Markdown

Installation

You can install the development version of quartify from GitHub:

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

Basic Usage

The main function of the package is rtoqmd(). Here’s a simple example:

library(quartify)

# Convert an R script to a Quarto document and render to HTML
rtoqmd("my_script.R", "my_document.qmd")

# Convert only, without rendering to HTML
rtoqmd("my_script.R", "my_document.qmd", render = FALSE)

By default, rtoqmd() will:
1. Create the .qmd file
2. Render it to HTML using Quarto
3. Open the HTML file in your default browser

Output File Locations

Understanding where files are created:

If you specify an output_file path: The .qmd file is created at that exact location, and the .html file (if rendered) is created in the same directory with the same base name.

# Creates: /path/to/my_analysis.qmd and /path/to/my_analysis.html
rtoqmd("script.R", "/path/to/my_analysis.qmd")

If you don’t specify output_file: The .qmd file is created in the same directory as your input R script, with the .R extension replaced by .qmd.

# If script.R is in /home/user/scripts/
# Creates: /home/user/scripts/script.qmd and /home/user/scripts/script.html
rtoqmd("/home/user/scripts/script.R")

Relative paths: If you use relative paths, files are created relative to your current working directory (check with getwd()).

# Creates files in your current working directory
rtoqmd("script.R", "output.qmd")

Using the RStudio Addin

quartify provides an interactive RStudio addin for easy conversion without writing code. This is perfect for quick conversions while working in RStudio.

Accessing the Addin

To use the addin:

From RStudio menu: Go to Addins > “Convert R to Quarto (rtoqmd)”
The interactive interface will open in a new window

Tip: You can also bind a keyboard shortcut to the addin for even faster access. Go to Tools > Modify Keyboard Shortcuts and search for “quartify” to assign your preferred shortcut.

Interface Overview

The addin features a modern, intuitive interface with:

Blue title bar with language switcher (EN/FR flags)
GENERATE button prominently placed at the top below the title bar, next to the quartify logo
Mode selector to choose between single file or directory conversion
File/directory browser for easy selection
Real-time validation and error messages

Single File Mode

Perfect for converting one R script at a time:

Select mode: Choose “Single File Mode”
Browse for input: Click “Browse” to select your R script
Set output location: Optionally specify where to save the .qmd file (defaults to same directory as input)
Configure options:
- Render to HTML: Check to automatically generate HTML output
- Open HTML: Check to open the result in your browser
Click GENERATE: The blue GENERATE button at the top starts the conversion

The addin will show success/error messages and provide clickable links to output files.

Directory Mode

Convert all R scripts in a directory at once:

Select mode: Choose “Directory Mode”
Browse for input directory: Select the folder containing your R scripts
Configure options:
- Recursive: Check to include subdirectories
- Render to HTML: Generate HTML for all files
- Create Book: Automatically create a _quarto.yml file to combine all documents into a Quarto book
Output directory (Optional): Choose where to save converted files (defaults to same location as input files)
Click GENERATE: Start batch conversion

Create Book Feature: When enabled, this option creates a _quarto.yml configuration file in the output directory, allowing you to render all converted documents as a unified Quarto book with automatic navigation and consistent styling. This is ideal for project documentation or analysis collections.

Advanced Features

The addin includes several quality-of-life improvements:

Volume management: Easily navigate across different drives and network locations
Path validation: Real-time checks for valid file/directory paths
Bilingual interface: Switch between English and French instantly
Persistent settings: Your last mode selection is remembered
Detailed feedback: Clear success/error messages with file counts and locations

When to Use the Addin

The RStudio addin is ideal for:

Interactive exploration: Testing conversion on sample scripts
One-off conversions: Quick document generation without scripting
Visual feedback: Seeing results immediately with the GUI
Learning the package: Understanding options before automating
Teaching: Demonstrating quartify features to colleagues

For batch processing or CI/CD pipelines, consider using the programmatic functions (rtoqmd(), rtoqmd_dir()) instead.

Using the Standalone Shiny App

For users working outside RStudio or wanting to share a conversion tool with their team, quartify provides a standalone Shiny application.

Launching the App

Simply run:

library(quartify)
quartify_app()

This opens the same intuitive interface as the RStudio addin, but in a standard browser window. The app can run on any system with R installed, making it perfect for:

Non-RStudio environments: Use with VS Code, Jupyter, or other IDEs
Shared team tools: Deploy on RStudio Connect or Shiny Server for team access
Demonstrations: Show quartify features without requiring RStudio
Remote work: Access from any browser if hosted on a server

Features

The standalone app includes all the same features as the RStudio addin:

Single File Mode: Convert individual R scripts with full control over output location and rendering options
Directory Mode: Batch convert entire folders with recursive directory scanning
Create Book: Generate _quarto.yml configuration for Quarto book projects
Bilingual Interface: Switch between English and French with flag buttons
Modern UI: Blue title bar, prominent GENERATE button, and intuitive layout

Comparison with Addin

Feature	RStudio Addin	Standalone App
Requires RStudio	Yes	No
Launch Method	Addins menu	`quartify_app()`
Interface	Gadget window	Browser window
File Browser	Native file system	Native file system
All Features	✓	✓
Shareable	No	Yes (can deploy)

Deployment Options

The standalone app can be deployed for team access:

Local Network:

# Run on a specific port accessible to your network
shiny::runApp(system.file("shiny", "quartify_app", package = "quartify"),
  host = "0.0.0.0", port = 3838
)

RStudio Connect / Shiny Server: Deploy as a standard Shiny application for enterprise-wide access.

Web Version

For environments where file system access is restricted (cloud deployments, sandboxed environments), use the web version:

quartify_app_web()

This version features:

File upload: Upload R scripts directly from your computer (single or multiple files)
File download: Download generated files as .zip archives with organized structure
ZIP structure:
- qmd/ folder with all Quarto markdown files and configuration
- html/ folder with complete rendered book (including index.html and all resources)
Batch conversion: Upload multiple files to create a complete Quarto book
Offline viewing: Downloaded ZIP contains everything needed to view the book offline
Same conversion logic: All quartify features available

Perfect for cloud deployments where direct file system access isn’t available. The downloaded ZIP is ready to extract and view immediately in any browser.

Structuring Your R Script

For optimal conversion, you need to follow specific commenting rules in your R script. quartify recognizes three types of lines:

0. Document Metadata (Optional)

You can define your document’s metadata directly in your R script using special comments at the beginning of the file. These metadata will appear in the YAML header of the generated Quarto document.

Recognized metadata:

Title: # Title : My title or # Titre : Mon titre
Author: # Author : My name or # Auteur : Mon nom
Date: # Date : 2025-11-28
Description: # Description : Description of your script

Tip - RStudio Snippets: quartify provides a function to automatically install useful snippets including header, callout, mermaid, and tabset:

# Install quartify snippets
install_quartify_snippets()

After installation and restarting RStudio, type the snippet name (e.g., header) followed by Tab in your R script to automatically insert the template.

You can also manually add snippets via Tools > Edit Code Snippets > R. See ?install_quartify_snippets for more details.

Complete example with metadata:

# Title : Iris Data Analysis
#
# Author : Jane Doe
#
# Date : 2025-11-28
#
# Description : Explore differences between iris species
#

library(dplyr)

## Descriptive Analysis ####

# Calculate statistics by species

iris |> 
  group_by(Species) |>
  summarize(mean_sepal = mean(Sepal.Length))

Behavior:

If metadata is found in the script, it overrides the rtoqmd() function parameters
If no metadata is found, the function’s title and author parameters are used
Metadata lines are automatically removed from the document body (they only appear in the YAML)
Date and Description metadata are optional

Rules for multi-line descriptions:

The Description field can span multiple lines. To continue the description on a new line:

Start the next line with # followed by at least one space and the continuation text
Continuation lines are automatically concatenated with a space
An empty line (or any other type of comment) ends the description

Example:

# Title : Iris Data Analysis
#
# Author : Jane Doe
#
# Date : 2025-11-28
#
# Description : This analysis explores differences between iris species
# using various statistical methods and visualization techniques
# to identify patterns and correlations.
#

library(dplyr)

This will produce in the YAML:

description: This analysis explores differences between iris species using various statistical methods and visualization techniques to identify patterns and correlations.

1. Code Sections (Headers)

Use RStudio code section syntax to create headers at different levels. These sections MUST follow this exact pattern:

Level 2: ## Title #### (at least 4 # symbols at the end)
Level 3: ### Title ==== (at least 4 = symbols at the end)
Level 4: #### Title ---- (at least 4 - symbols at the end)

Important rules:

There must be at least one space between the title text and the trailing symbols
The trailing symbols must be at least 4 characters long
You can use #, =, or - interchangeably (e.g., ## Title ==== works), but following the RStudio convention is recommended for consistency
This follows the RStudio code sections convention

Example:

## Data Loading ####

### Import CSV ====

#### Check Missing Values ----

2. Regular Comments (Text)

Single # comments become explanatory text in the Quarto document:

# This is a regular comment
# It will appear as plain text in the output
# Use these to explain what your code does

Rules:

Start with a single # followed by a space (no space before the #)
Multiple consecutive comment lines are grouped together (with no empty lines between them)
Empty comment lines separate comment blocks
Markdown Tables: You can include Markdown tables in comments. Consecutive comment lines will be preserved together, allowing proper table rendering

⚠️ Important for text conversion:

For a comment to be correctly converted to Quarto text, the line must start with # without any leading space. If you have indentation spaces before the #, the comment will be ignored and remain in the code chunk.

Correct example:

# This will be converted to text
result <- mean(x)

Incorrect example (comment stays in code):

if (condition) {
  # This will remain an R comment in the chunk
  result <- mean(x)
}

You can use this rule to split a long code chunk into multiple parts. By inserting a comment at the start of a line (no space before #) between two code blocks, this comment will be converted to text and naturally create two separate chunks:

data <- read.csv("file.csv")
data_clean <- na.omit(data)

# This comment splits the chunk into two parts

result <- mean(data_clean$value)
plot(result)

This will create two separate chunks instead of one large chunk.

Important for Markdown Tables: Table lines must be isolated from other comments with an empty line before and after the table. This ensures the table is treated as a separate block and will render correctly.

Markdown table example:

# Analysis results:

# | fruit  | price  |
# |--------|--------|
# | apple  | 2.05   |
# | pear   | 1.37   |
# | orange | 3.09   |
#
# The table above is properly isolated.

Tip: Use RStudio’s Comment/Uncomment shortcut (Ctrl+Shift+C on Windows/Linux or Cmd+Shift+C on Mac) to quickly add or remove comments from your code.

data <- read.csv("file.csv")
data_clean <- na.omit(data)

# This comment splits the chunk into two parts

result <- mean(data_clean$value)
plot(result)

This will create two separate chunks instead of one large chunk.

Markdown table example:

# Analysis results:

# | fruit  | price  |
# |--------|--------|
# | apple  | 2.05   |
# | pear   | 1.37   |
# | orange | 3.09   |
#
# The table above is properly isolated.

Tip: Use RStudio’s Comment/Uncomment shortcut (Ctrl+Shift+C on Windows/Linux or Cmd+Shift+C on Mac) to quickly add or remove comments from your code.

3. Roxygen2 Documentation

If your R script contains roxygen2 documentation blocks (lines starting with #'), quartify automatically converts them into elegant callout-note sections with the function name:

Input (R script):

#' Add two numbers together
#'
#' @param x A numeric value
#' @param y A numeric value
#' @return The sum of x and y
#' @examples
#' add_numbers(2, 3)
#' @export
add_numbers <- function(x, y) {
  return(x + y)
}

Output (Quarto document):

::: {.callout-note}
## Documentation - add_numbers

Add two numbers together

@param x A numeric value
@param y A numeric value
@return The sum of x and y
@examples
add_numbers(2, 3)
@export
:::


``` r
add_numbers <- function(x, y) {
  return(x + y)
}
```

Rules:

Roxygen2 blocks (lines starting with #') are automatically detected
The function name is extracted from the following function definition
All roxygen2 tags (@param, @return, @examples, @export, etc.) are preserved
The documentation appears as a beautiful callout box above the code
Works with rtoqmd(), rtoqmd_dir(), and all Shiny applications

This feature is particularly useful when documenting R packages or sharing code with full API documentation. The roxygen2 blocks remain readable in the Quarto output without requiring users to build package documentation.

4. Code Lines

Any line that is NOT a comment becomes executable R code:

library(dplyr)

iris |> 
  filter(Species == "setosa") |>
  summarize(mean_length = mean(Sepal.Length))

Rules:

Consecutive code lines are grouped into a single code chunk
Empty lines between code blocks are ignored
Code blocks are separated by comments or section headers

Important: You can include comments WITHIN code blocks. These comments will be preserved inside the R code chunk:

iris %>% 
  # Select a column
  select(Species)

This will render as:


``` r
iris %>%
  # Select a column
  select(Species)
```

The difference:
- Comments at the start of a line (standalone) → become text OUTSIDE code blocks
- Comments within code (indented or part of a pipeline) → stay INSIDE code blocks

Complete Example: example.R

Here’s the complete example R script included in the package:

library(dplyr)

## Title 2 ####

### Title 3 ====

# Start of statistical processing
# Counting the number of observations by species

iris |> 
  count(Species)

### Title 3 ====

# Filter the data.frame on Species "setosa"

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

#### Title 4 ----

# Select column Species

iris %>% 
  # Select a column
  select(Species)

This script demonstrates:

Code without section: library(dplyr) becomes a code chunk
Section headers: ## Title 2 ####, ### Title 3 ====, #### Title 4 ----
Standalone comments: # Select column Species becomes readable text
Inline comments: # Select a column stays inside the code block
Code blocks: Separated by standalone comments or sections

Customization Options

You can customize the output document with several parameters:

rtoqmd(
  input_file = "my_script.R",
  output_file = "my_document.qmd",
  title = "My Analysis Report",
  author = "Your name",
  format = "html"
)

Parameters

input_file: Path to your R script
output_file: Path for the Quarto output document (optional)
title: Document title (default: “My title”)
author: Author name (default: “Your name”)
format: Output format (default: “html”)
render: Render HTML from the .qmd (default: TRUE)
open_html: Open HTML in browser (default: FALSE)
code_fold: Fold code blocks by default (default: FALSE)
number_sections: Number sections automatically (default: TRUE)

Converting the Example

To convert the above example script:

# Get the example file path
example_file <- system.file("examples", "example.R", package = "quartify")

# Convert it
rtoqmd(
  input_file = example_file,
  output_file = "iris_analysis.qmd",
  title = "Iris Dataset Analysis",
  author = "Data Analyst"
)

Generated Output

This produces the following Quarto document:

---
title: "Iris Dataset Analysis"
author: "Data Analyst"
format:
  html:
    embed-resources: true
    code-fold: false
toc: true
toc-title: Table of Contents
toc-depth: 4  
toc-location: left
execute: 
  eval: false
  echo: true
output: 
  html_document:
  number_sections: TRUE
  output-file: iris_analysis.html
---


``` r
library(dplyr)
```

## Title 2

### Title 3

Start of statistical processing

Counting the number of observations by species


``` r
iris |>
  count(Species)
```

### Title 3

Filter the data.frame on Species "setosa"


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

#### Title 4

Select column Species


``` r
iris %>%
  # Select a column
  select(Species)
```

Note how:

Each code section becomes an appropriate markdown header
Comments become readable text paragraphs
Inline comments (in code) are preserved in code blocks
Code blocks are properly formatted with syntax highlighting
The table of contents will show the hierarchical structure

Important Note on Code Chunks:
Generated code chunks use standard R chunks.
The YAML header includes global execute options (eval: false and echo: true), which create non-executable code blocks.
Additionally, HTML format uses embed-resources: true to create self-contained HTML files (see the Quarto documentation).
This is intentional - quartify is designed to create static documentation of your R script, not an executable notebook.
The code is displayed with syntax highlighting for reading and documentation purposes, but will not be executed when rendering the Quarto document.

This approach is ideal for:

Documenting existing scripts without modifying their execution
Sharing code examples that readers can copy and run in their own environment
Ensuring the documentation process doesn’t interfere with your original script’s behavior

Rendering Output

Automatic Rendering (Recommended)

By default, rtoqmd() automatically renders your Quarto document to HTML:

# This will create both .qmd and .html files, then open the HTML
rtoqmd(example_file, "iris_analysis.qmd")

The function will: 1. Check if Quarto is installed (by default)
2. Render the .qmd file to HTML (by default)
3. Open the HTML file in your default browser (if open_html = TRUE)

If you don’t want automatic HTML rendering, set render = FALSE:

rtoqmd(example_file, "iris_analysis.qmd", render = FALSE)

Manual Rendering

You can also manually render the HTML file using:

quarto render iris_analysis.qmd

Or from R:

quarto::quarto_render("iris_analysis.qmd")

Note: Quarto must be installed on your system. Download it from quarto.org.

Batch Directory Conversion

quartify v0.0.7 introduces powerful batch conversion capabilities through multiple interfaces. Choose the method that best fits your workflow.

Using RStudio Addin or Standalone App

The most intuitive way to batch convert files is via Directory Mode in the RStudio addin or standalone app:

# Launch standalone app
quartify_app()

# Or use RStudio addin: Addins > "Convert R to Quarto (rtoqmd)"

Directory Mode Features (v0.0.7):

Browse Directory: Select the folder containing your R scripts
Recursive Option: Include or exclude subdirectories
Output Directory: Optionally specify a different location for converted files (new in v0.0.7!)
Create Book Checkbox: Automatically generate _quarto.yml to combine all documents into a Quarto book (new in v0.0.7!)
Render Option: Choose whether to render HTML files for all scripts
One-Click Conversion: Click the GENERATE button at the top to convert all files

New in v0.0.7: The output directory feature allows you to keep your source R scripts separate from generated .qmd files. Combined with the “Create Book” option, you can instantly create a complete Quarto book project from a collection of R scripts.

Example workflow:

Input directory: ~/my-project/scripts/ (contains 10 R scripts)
Output directory: ~/my-project/docs/ (where you want .qmd files)
Enable “Create Book”: Generates ~/my-project/docs/_quarto.yml
Result: Complete Quarto book ready to render with quarto render

Using Web Interface

For environments without direct file system access:

quartify_app_web()

In batch mode, you can:
- Upload multiple R files at once
- Select a directory containing your R scripts

The interface will convert all files and provide a downloadable .zip archive.

Using R Functions

To convert all R scripts in a directory (including subdirectories) programmatically, use rtoqmd_dir():

# Convert all R scripts in a directory
rtoqmd_dir("path/to/scripts")

# Convert and render HTML files
rtoqmd_dir("path/to/scripts", render = TRUE)

# With custom author and title prefix
rtoqmd_dir("path/to/scripts",
  title_prefix = "Analysis: ",
  author = "Data Team"
)

# Exclude certain files (e.g., test files)
rtoqmd_dir("path/to/scripts",
  exclude_pattern = "test_.*\\.R$"
)

# Non-recursive (current directory only)
rtoqmd_dir("path/to/scripts", recursive = FALSE)

This function: - Recursively searches for all .R files in the directory - Converts each file to .qmd in the same location - Shows a conversion summary with success/failure counts - Returns a data frame with results for each file

CI/CD Integration

You can use quartify in your CI/CD pipelines to automatically generate documentation from your R scripts. This is useful for:

Version controlling only R scripts (not generated documentation)
Automatically generating .qmd and .html files in CI/CD
Providing documentation artifacts for each commit/merge request

GitHub Actions

Create .github/workflows/generate-docs.yml:

name: Generate Documentation

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

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.5.1'
      
      - name: Install Quarto
        uses: quarto-dev/quarto-actions/setup@v2
      
      - name: Install R dependencies
        run: |
          install.packages(c("remotes", "dplyr"))
          remotes::install_github("ddotta/quartify")
        shell: Rscript {0}
      
      - name: Convert R scripts to Quarto
        run: |
          library(quartify)
          # Convert all R scripts in a directory
          rtoqmd_dir("scripts/", render = TRUE, author = "Data Team")
        shell: Rscript {0}
      
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: documentation
          path: |
            scripts/**/*.qmd
            scripts/**/*.html

GitLab CI

Create .gitlab-ci.yml:

generate-docs:
  image: rocker/r-ver:4.5.1
  
  before_script:
    # Install Quarto
    - apt-get update
    - apt-get install -y curl
    - curl -LO https://quarto.org/download/latest/quarto-linux-amd64.deb
    - dpkg -i quarto-linux-amd64.deb
    
    # Install R packages
    - R -e "install.packages(c('remotes', 'dplyr'))"
    - R -e "remotes::install_github('ddotta/quartify')"
  
  script:
    # Convert all R scripts to Quarto and render HTML
    - R -e "quartify::rtoqmd_dir('scripts/', render = TRUE, author = 'Data Team')"
  
  artifacts:
    paths:
      - scripts/**/*.qmd
      - scripts/**/*.html
    expire_in: 30 days
  
  only:
    - main
    - merge_requests

Single File Conversion in CI/CD

To convert a single R script:

# GitHub Actions
- name: Convert single script
  run: |
    library(quartify)
    rtoqmd("analysis.R", "analysis.qmd", 
           title = "My Analysis",
           author = "Data Team",
           render = TRUE)
  shell: Rscript {0}

# GitLab CI
script:
  - R -e "quartify::rtoqmd('analysis.R', 'analysis.qmd', title = 'My Analysis', author = 'Data Team', render = TRUE)"

Best Practices for CI/CD

Add to .gitignore: Exclude generated files from version control
```
# .gitignore
*.qmd
*.html
*_files/
```
Artifact retention: Set appropriate expiration for artifacts
- Short duration (7 days) for feature branches
- Long duration (90+ days) for main branch

Conditional execution: Generate documentation only if R scripts change

# GitHub Actions
on:
  push:
    paths:
      - 'scripts/**/*.R'

Error handling: Use render = FALSE to debug conversion issues

# First convert without rendering
rtoqmd_dir("scripts/", render = FALSE)
# Then render separately if needed

Use Cases

quartify is particularly useful for:

Documentation: Transform working scripts into documentation
Code Review: Present code in a more accessible format
Batch Conversion: Automatically convert all scripts in a project

Callouts (Highlighted Boxes)

Callouts are special blocks that highlight important information in your Quarto documents. quartify supports automatic conversion of callout comments.

Syntax

In your R script, use this syntax:

# callout-note - Important Note
# This is the content of the note.
# It can span multiple lines.

# Code or an empty line ends the callout
x <- 1

This converts to:

::: {.callout-note title="Important Note"}
This is the content of the note.
It can span multiple lines.
:::

Callout Types

Five callout types are supported:

# callout-note - Blue information box
# callout-tip - Green tip box
# callout-warning - Orange warning box
# callout-caution - Red caution box
# callout-important - Red important box

With or Without Title

With title:

# callout-tip - Useful Tip
# Use callouts to highlight key information.

Without title:

# callout-tip
# Use callouts to highlight key information.

Examples

# callout-note - Data Requirements
# Input data must contain columns: Species, Sepal.Length, Petal.Length

# callout-warning
# This operation may take several minutes with large datasets

# callout-tip - Performance Optimization
# Use data.table for datasets larger than 1 GB

library(dplyr)
iris %>% head()

Rules

Callout starts with # callout-TYPE (optionally followed by - Title)
All following comment lines are part of the callout content
Callout ends when encountering:
- An empty line
- A code line
- Another section or callout
Title is optional (omit the - Title part)

Tip: Use the install_quartify_snippets() function to add a callout snippet to your RStudio. Type callout followed by Tab to quickly insert the callout template.

Mermaid Diagrams

Create flowcharts, sequence diagrams, and other visualizations with Mermaid syntax. Mermaid diagrams render directly in HTML output.

Syntax

In your R script, start with #| mermaid, add options with #|, then the diagram content:

#| mermaid
#| eval: true
flowchart TD
    A[Start] --> B[Process Data]
    B --> C{Valid?}
    C -->|Yes| D[Save]
    C -->|No| E[Error]
    D --> F[End]
    E --> F

This converts to a Quarto Mermaid chunk that renders as an interactive diagram in HTML.

Diagram Types

Mermaid supports many diagram types:

Flowcharts:

#| mermaid
#| eval: true
flowchart LR
    A[Input] --> B[Processing]
    B --> C[Output]

Sequence Diagrams:

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

Class Diagrams:

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

Rules

Start with the #| mermaid comment
Add chunk options with #| prefix (e.g., #| eval: true)
Diagram content follows without # prefix
Chunk ends at the first empty line or comment line
Options are automatically converted to Quarto format (%%|)

Complete Example

See the complete example file with multiple diagram types:

# Locate the Mermaid example file
mermaid_file <- system.file("examples", "example_mermaid.R", package = "quartify")

# Convert and render
rtoqmd(mermaid_file, render = TRUE, open_html = TRUE)

Tip: Use install_quartify_snippets() to add a mermaid snippet. Type mermaid + Tab to insert the diagram template.

More Mermaid Resources:

Mermaid Documentation
Mermaid Live Editor - Test your diagrams
Quarto Mermaid Guide

Tabsets (Tabs)

Tabsets allow you to organize related content in interactive tabs, perfect for showing alternative views, different analyses, or grouped visualizations. This feature uses the same intuitive syntax as callouts.

Basic Syntax

To create a tabset:

Start tabset container: Use # tabset on a line by itself
Define each tab: Use # tab - Tab Title on a line by itself
Add content: Add comments and code for each tab
Automatic closing: Tabset closes at the next section header

Syntax in R script:

# tabset
# tab - Summary Statistics
# Here are the summary statistics for the iris dataset:
summary(iris)

Resulting Quarto:

::: {.panel-tabset}

## Summary Statistics

Here are the summary statistics for the iris dataset:


``` r
summary(iris)
#>   Sepal.Length    Sepal.Width     Petal.Length    Petal.Width   
#>  Min.   :4.300   Min.   :2.000   Min.   :1.000   Min.   :0.100  
#>  1st Qu.:5.100   1st Qu.:2.800   1st Qu.:1.600   1st Qu.:0.300  
#>  Median :5.800   Median :3.000   Median :4.350   Median :1.300  
#>  Mean   :5.843   Mean   :3.057   Mean   :3.758   Mean   :1.199  
#>  3rd Qu.:6.400   3rd Qu.:3.300   3rd Qu.:5.100   3rd Qu.:1.800  
#>  Max.   :7.900   Max.   :4.400   Max.   :6.900   Max.   :2.500  
#>        Species  
#>  setosa    :50  
#>  versicolor:50  
#>  virginica :50  
#>                 
#>                 
#>

:::


### Rules

- `# tabset` must be on a line by itself (with optional leading/trailing spaces)
- Each tab starts with `# tab - Title` where `Title` is the tab label
- Tab content includes all comments and code until the next tab or tabset end
- Tabsets automatically close at RStudio section headers (`##`, `###`, `####`)
- You can have multiple tabsets in the same document
- Empty lines within tabs are preserved

### Complete Example

See the complete example file with multiple tabsets:

```r
# Locate the tabset example file
tabset_file <- system.file("examples", "example_tabset.R", package = "quartify")

# Convert and render
rtoqmd(tabset_file, render = TRUE, open_html = TRUE)

Tip: Use install_quartify_snippets() to add a tabset snippet. Type tabset + Tab to insert the tabset template.

More Resources on Tabsets:

Quarto Tabset Documentation
Combine tabsets with callouts for rich, organized documentation

Comment Rules Summary

Type	Syntax	Result	Example
Level 2 Header	`## Title ####`	Markdown `## Title`	`## Data Analysis ####`
Level 3 Header	`### Title ====`	Markdown `### Title`	`### Preprocessing ====`
Level 4 Header	`#### Title ----`	Markdown `#### Title`	`#### Remove NA ----`
Comment	`# Text`	Text paragraph	`# This filters the data`
Callout	`# callout-TYPE - Title`	Quarto callout block	`# callout-note - Important`
Mermaid Diagram	`#\| mermaid`	Mermaid diagram chunk	`#\| mermaid` + content
Tabset	`# tabset`, `# tab - Title`	Tabbed panel	`# tabset` + tabs
Code	No `#` prefix	R code chunk	`iris %>% filter(...)`
Inline Comment	`# Text` in code	Stays in chunk	`iris %>% # comment`

Critical Rules to Avoid Errors:

Spacing: Always include a space after # for comments and section headers
Trailing Symbols: Section headers MUST have at least 4 trailing symbols
Symbol Flexibility: You can use #, =, or - interchangeably for trailing symbols, but following the RStudio convention is recommended
Roxygen Comments: Lines starting with #' are ignored (for package development)
Comment Context: Comments at line start become text; comments within code stay in code blocks
Keyboard Shortcut: Use Ctrl+Shift+C (Windows/Linux) or Cmd+Shift+C (Mac) to quickly comment/uncomment

Code Quality Integration

quartify integrates with styler and lintr to provide automatic code quality checks in your documentation.

Using styler

The use_styler parameter automatically formats your code according to the tidyverse style guide:

# Create a script with style issues
temp_script <- tempfile(fileext = ".R")
writeLines(c(
  "x = 3  # Should use <- instead of =",
  "y<-2   # Missing spaces",
  "z <- mean(c(1,2,3))  # Missing spaces in function call"
), temp_script)

# Convert with styler
rtoqmd(temp_script, "styled_output.qmd", use_styler = TRUE)

The generated document will include tabsets showing: - Original Code: Your code as written - Styled Code: The tidyverse-formatted version

Using lintr

The use_lintr parameter performs code quality checks:

# Convert with styler and lintr
rtoqmd(temp_script, "quality_output.qmd",
  use_styler = TRUE,
  use_lintr = TRUE
)

Tabsets will include: - Original Code: Your code - Styled Code: Formatted version - Lint Issues: List of style violations and suggestions

Applying styler to Source Files

Use apply_styler = TRUE to directly modify your source R script:

# This will modify the original R file
rtoqmd("my_script.R", "output.qmd",
  use_styler = TRUE,
  apply_styler = TRUE
)

Warning: apply_styler = TRUE modifies your original R script file. Consider using version control or backups before using this option.

Example Output

Try the included example:

example_file <- system.file("examples", "example_code_quality.R",
  package = "quartify"
)
rtoqmd(example_file, "quality_demo.qmd",
  use_styler = TRUE,
  use_lintr = TRUE,
  render_html = TRUE,
  open_html = TRUE
)

Tips and Best Practices

Start with structure: Define your section headers first to create the document outline
Use consistent levels: Follow a logical hierarchy (2 → 3 → 4, don’t skip levels)
Add explanatory text: Use regular comments to explain what your code does
Group related code: Keep related operations together; they’ll be grouped in the same chunk
Test incrementally: Start with a small script to see how conversion works
Navigate easily: In RStudio, use document outline (Ctrl+Shift+O) to see your structure
Comment liberally: More comments = better documentation in the final Quarto document
Use quality checks: Enable use_styler and use_lintr for teaching materials or code reviews

Next Steps

Now that you’ve learned the basics of quartify, explore more advanced features:

📖 Advanced Features Guide - Learn about:

Customization Options: Themes, rendering options, output configuration
Batch Conversion: Convert entire directories with rtoqmd_dir()
Quarto Books: Automatically create navigable book projects
Code Quality Integration: styler and lintr for code formatting and quality checks
Special Features: Mermaid diagrams, callouts, and tabsets
CI/CD Integration: Automate documentation generation

🇫🇷 Version française: French version of this guide

Conclusion

quartify makes it easy to transform your R scripts into professional Quarto documents without manual reformatting. By following RStudio code section conventions, you can automatically generate well-structured, reproducible documentation from your existing code with proper navigation hierarchy.