Install quartify RStudio Snippets

Description

Installs useful RStudio snippets for working with quartify. These snippets help you quickly insert common structures when writing R scripts that will be converted to Quarto documents.

Usage

install_quartify_snippets(
  backup = TRUE,
  path = file.path(tempdir(), "r.snippets")
)

Arguments

Details

The following snippets are installed:

- **header**: Insert a standard R script header with Title, Author, Date, and Description - **callout**: Insert a Quarto callout structure - **mermaid**: Insert a Mermaid diagram chunk - **tabset**: Insert a tabset structure

By default the snippets are written to a temporary file (inside 'tempdir()') to comply with CRAN's restriction on writing to the user's filespace during examples, vignettes, and tests. To install in your actual RStudio snippets file, provide the explicit path via 'path', for example: - Windows: ' - Mac/Linux: '~/.config/rstudio/snippets/r.snippets'

If you already have custom snippets, this function will append the quartify snippets to your existing file. If quartify snippets were previously installed, they will be automatically removed and replaced with the new version.

The function will automatically open the snippets file in RStudio if available. Simply save the file (Ctrl+S / Cmd+S) to reload the snippets immediately without restarting RStudio. Then type the snippet name (e.g., 'header') and press Tab to insert the template.

Value

Invisibly returns the path to the snippets file.

Examples

if (interactive()) {
  # Install quartify snippets to RStudio
  install_quartify_snippets()

  # Install without backup
  install_quartify_snippets(backup = FALSE)
}

# For testing: install to temp directory
temp_snippets <- file.path(tempdir(), "r.snippets")
install_quartify_snippets(path = temp_snippets)

Launch Quartify Standalone Application

Description

Standalone Shiny application for converting R scripts to Quarto markdown documents. Works in any R environment (RStudio, Positron, VS Code, etc.) without requiring the RStudio API.

Usage

quartify_app(launch.browser = TRUE, port = NULL)

Arguments

Value

No return value, called for side effects (launches a Shiny application).

Examples

if (interactive()) {
  # Launch the Shiny app in browser (works in any IDE)
  quartify_app()

  # Use in Positron or VS Code
  library(quartify)
  quartify_app()

  # Specify a port
  quartify_app(port = 3838)
}

Launch Quartify Web Application

Description

Web-deployable Shiny application with file upload/download capabilities for converting R scripts to Quarto markdown documents. Suitable for deployment on Shiny Server, ShinyApps.io, or other web hosting platforms.

Usage

quartify_app_web(launch.browser = TRUE, port = NULL)

Arguments

Value

No return value, called for side effects (launches a Shiny application).

Examples

if (interactive()) {
  quartify_app_web()
}

Convert R Script to Quarto Markdown

Description

This function converts an R script to Quarto markdown format (.qmd), enabling you to leverage all modern Quarto features. Unlike knitr::spin() which generates R Markdown (.Rmd), rtoqmd() creates Quarto documents with access to advanced publishing capabilities, modern themes, native callouts, Mermaid diagrams, and the full Quarto ecosystem.

Usage

rtoqmd(
  input_file,
  output_file = NULL,
  title = "My title",
  author = "Your name",
  format = "html",
  theme = NULL,
  render_html = TRUE,
  output_html_file = NULL,
  open_html = FALSE,
  code_fold = FALSE,
  number_sections = TRUE,
  lang = "en",
  show_source_lines = TRUE,
  use_styler = FALSE,
  use_lintr = FALSE,
  apply_styler = FALSE
)

Arguments

Details

It recognizes RStudio code sections with different levels: - ## Title #### creates a level 2 header - ### Title ==== creates a level 3 header - #### Title —- creates a level 4 header Regular comments are converted to plain text. Code blocks are wrapped in standard R code chunks. The YAML header includes execute: eval: false and execute: echo: true options for static documentation purposes, and embed-resources: true to create self-contained HTML files. See https://quarto.org/docs/output-formats/html-basics.html#self-contained.

Value

Invisibly returns NULL. Creates a .qmd file and optionally renders it to HTML.

Metadata Detection

The function automatically extracts metadata from special comment lines in your R script:

• Title: Use # Title : Your Title or # Titre : Votre Titre

• Author: Use # Author : Your Name or # Auteur : Votre Nom

• Date: Use # Date : YYYY-MM-DD

• Description: Use # Description : Your description (also accepts # Purpose or # Objectif)

If metadata is found in the script, it will override the corresponding function parameters. These metadata lines are removed from the document body and only appear in the YAML header.

The Description field supports multi-line content. Continuation lines should start with # followed by spaces and the text. The description ends at an empty line or a line without #.

Hidden Comments

Comments that start with # immediately followed by a non-space character (e.g., #NOTE:, #TODO:, #DEBUG) are completely ignored during conversion and will not appear in the Quarto output. This allows you to include private notes, debugging comments, or development annotations in your R scripts that won't be visible in the rendered documentation.

Only comments with a space after # (e.g., # This is a comment) are converted to text in the output.

Callouts

The function converts special comment patterns into Quarto callouts. Callouts are special blocks that highlight important information. Supported callout types: note, tip, warning, caution, important.

Syntax:

• With title: # callout-tip - Your Title

• Without title: # callout-tip

All subsequent comment lines become the callout content until an empty line or code is encountered.

Example in R script:

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

x <- 1

Becomes in Quarto:

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

Mermaid Diagrams

The function supports Mermaid diagrams for flowcharts, sequence diagrams, and visualizations. Mermaid chunks start with a special comment, followed by options and diagram content. Options use hash-pipe syntax and are converted to percent-pipe in the Quarto output. Diagram content should not start with hash symbols. The chunk ends at a blank line or comment. Supported types: flowchart, sequence, class, state, etc. See example file in inst/examples/example_mermaid.R.

Tabsets

Create tabbed content panels for interactive navigation between related content. Use hash tabset to start a tabset container, then define individual tabs with hash tab - Title. Each tab can contain text, code, and other content. The tabset closes automatically when a new section starts. Example: hash tabset, hash tab - Plot A, code or text content, hash tab - Plot B, more content.

Roxygen2 Documentation

The function automatically detects and formats roxygen2 documentation blocks (starting with #') into structured callouts that resemble pkgdown reference pages. The formatted documentation includes:

• Title: Extracted from @title tag or first roxygen comment line

• Description: From @description tag or initial paragraph

• Usage: Function signature with parameters

• Arguments: Each parameter from @param tags, formatted with parameter name in bold

• Value: Return value description from @return tag

• Details: Additional details from @details tag

• Examples: Code examples from @examples tag, displayed in R code blocks

LaTeX-style formatting is automatically converted to Markdown: \href{url}{text} becomes [text](url), \code{text} becomes `text`, \strong{text} becomes **text**, and \emph{text} becomes *text*. Section headers within the callout use bold text instead of Markdown headers to avoid interfering with the document's table of contents. See example file in inst/examples/example_roxygen.R.

Examples

# Use example file included in package
example_file <- system.file("examples", "example.R", package = "quartify")

# Convert and render to HTML (output in temp directory)
output_qmd <- file.path(tempdir(), "output.qmd")
rtoqmd(example_file, output_qmd)

# Convert only, without rendering
rtoqmd(example_file, output_qmd, render_html = FALSE)

# Example with metadata in the R script:
# Create a script with metadata
script_with_metadata <- tempfile(fileext = ".R")
writeLines(c(
  "# Title : My Analysis",
  "# Author : Jane Doe", 
  "# Date : 2025-11-28",
  "# Description : Analyze iris dataset",
  "",
  "library(dplyr)",
  "iris %>% head()"
), script_with_metadata)

# Convert - metadata will override function parameters
output_meta <- file.path(tempdir(), "output_with_metadata.qmd")
rtoqmd(script_with_metadata, output_meta)

# Example with code quality checks (requires styler and lintr packages)
script_with_style_issues <- tempfile(fileext = ".R")
writeLines(c(
  "# Script with style issues",
  "",
  "x = 3  # Should use <- instead of =",
  "y <- 2",
  "",
  "z <- 10"
), script_with_style_issues)

# Convert with styler formatting
output_styled <- file.path(tempdir(), "output_styled.qmd")
rtoqmd(script_with_style_issues, output_styled, use_styler = TRUE)

# Convert with both styler and lintr
output_quality <- file.path(tempdir(), "output_quality.qmd")
rtoqmd(script_with_style_issues, output_quality, 
       use_styler = TRUE, use_lintr = TRUE)

Convert Active R Script to Quarto Markdown

Description

RStudio add-in that converts the currently active R script in the editor to a Quarto markdown document. Uses a Shiny interface for parameter input.

Usage

rtoqmd_addin()

Value

No return value, called for side effects (launches an interactive Shiny gadget).

Convert All R Scripts in a Directory to Quarto Markdown

Description

This function recursively searches for all R script files (.R) in a directory and its subdirectories, and converts each one to a Quarto markdown document (.qmd). The output files are created in the same directories as the input files.

Usage

rtoqmd_dir(
  dir_path,
  title_prefix = NULL,
  author = "Your name",
  format = "html",
  theme = NULL,
  render_html = FALSE,
  output_html_dir = NULL,
  open_html = TRUE,
  code_fold = FALSE,
  number_sections = TRUE,
  recursive = TRUE,
  pattern = "\\.R$",
  exclude_pattern = NULL,
  create_book = TRUE,
  book_title = "R Scripts Documentation",
  output_dir = NULL,
  language = "en",
  use_styler = FALSE,
  use_lintr = FALSE,
  apply_styler = FALSE
)

Arguments

Details

Supports all features of rtoqmd, including:

• Metadata detection (Title, Author, Date, Description)

• RStudio section headers

• Callouts (note, tip, warning, caution, important)

• Code blocks and comments

See rtoqmd for details on callout syntax and metadata detection.

Value

Invisibly returns a data frame with conversion results (file paths and status)

Note

Existing .qmd and .html files will be automatically overwritten during generation to ensure fresh output.

Examples

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

# Convert and render all scripts
rtoqmd_dir("path/to/scripts", render_html = TRUE)

# Create a Quarto book with automatic navigation
rtoqmd_dir(
  dir_path = "path/to/scripts",
  output_html_dir = "path/to/scripts/documentation",
  render_html = TRUE,
  author = "Your Name",
  book_title = "My R Scripts Documentation",
  open_html = TRUE
)

# Create a Quarto book in French
rtoqmd_dir(
  dir_path = "path/to/scripts",
  output_html_dir = "path/to/scripts/documentation",
  render_html = TRUE,
  author = "Votre Nom",
  book_title = "Documentation des Scripts R",
  language = "fr"
)

# Convert 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 (only current directory)
rtoqmd_dir("path/to/scripts", recursive = FALSE)

# Reproducible example with sample scripts
example_dir <- system.file("examples", "book_example", package = "quartify")
if (example_dir != "") {
  rtoqmd_dir(
    dir_path = example_dir,
    output_html_dir = file.path(example_dir, "documentation"),
    render_html = TRUE,
    open_html = TRUE
  )
}

## End(Not run)