Quick Start

Your First Diagram in 2 Minutes

Step 1: Install

install.packages("putior")
library(putior)

Step 2: Add Annotations to Your Code

Add # put comments to your R scripts:

# my_analysis.R
# put label:"Load Data", output:"raw_data"
data <- read.csv("sales.csv")

# put label:"Clean Data", input:"raw_data", output:"clean_data"
clean <- data[complete.cases(data), ]

# put label:"Generate Report", input:"clean_data", output:"report.html"
rmarkdown::render("report.Rmd")

Step 3: Generate Diagram

workflow <- put("my_analysis.R")
put_diagram(workflow)

That’s it! You’ll see a flowchart like this:

---
config:
  layout: "dagre"
  look: "classic"
  flowchart:
    wrappingWidth: 200
    minNodeWidth: 0
---
flowchart TD
    accDescr: Workflow with 3 steps and 3 data files.
    load(["Load Data"])
    clean["Clean Data"]
    report[["Generate Report"]]

    %% Connections
    load --> clean
    clean --> report

    %% Styling
    classDef inputStyle fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e40af
    class load inputStyle
    classDef processStyle fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#5b21b6
    class clean processStyle
    classDef outputStyle fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#15803d
    class report outputStyle

Try It Now

# Create a temporary file with annotations
temp_file <- tempfile(fileext = ".R")
writeLines(c(
  '# put label:"Extract", output:"raw.csv"',
  'data <- read.csv("source.csv")',
  '',
  '# put label:"Transform", input:"raw.csv", output:"clean.csv"',
  'clean <- transform(data)',
  '',
  '# put label:"Load", input:"clean.csv", output:"database.db"',
  'write_to_db(clean)'
), temp_file)

# Scan, then clean up
workflow <- put(temp_file)
unlink(temp_file)

# Visualize
cat("```mermaid\n", put_diagram(workflow, output = "raw"), "\n```\n", sep = "")
---
config:
  layout: "dagre"
  look: "classic"
  flowchart:
    wrappingWidth: 200
    minNodeWidth: 0
---
flowchart TD
    accDescr: Workflow with 3 steps and 3 data files.
    node_67886935_afce_420f_b107_4afd3442e39d["Extract"]
    e60669dc_66f9_4d4b_8280_0d7b5c278801["Transform"]
    node_043a9b41_d90f_4c1d_bcd1_01b384c6e9f7["Load"]

    %% Connections
    node_67886935_afce_420f_b107_4afd3442e39d --> e60669dc_66f9_4d4b_8280_0d7b5c278801
    e60669dc_66f9_4d4b_8280_0d7b5c278801 --> node_043a9b41_d90f_4c1d_bcd1_01b384c6e9f7

Annotation Syntax at a Glance

# put label:"Step Name", input:"file.csv", output:"result.csv"
Field Purpose Required
label Human-readable name Yes
input Files/data consumed No
output Files/data produced No
id Unique identifier No (auto-generated)
node_type input, process, output, decision, start, end No (defaults to process)

Multiple inputs/outputs: Use commas: input:"a.csv, b.csv"

Multi-Language Support

putior works with 30+ languages. Comment prefix is auto-detected:

Language Annotation
R, Python, Shell # put label:"..."
SQL, Lua -- put label:"..."
JavaScript, Go, Rust // put label:"..."
MATLAB % put label:"..."

Common Patterns

Scan a Directory

workflow <- put("./src/")
put_diagram(workflow)

Include Subdirectories

workflow <- put("./project/", recursive = TRUE)

Auto-Detect Workflow (No Annotations!)

# Automatically detect file I/O from code
workflow <- put_auto("./src/")
put_diagram(workflow)

Choose a Theme

put_diagram(workflow, theme = "github")  # or: light, dark, minimal, viridis

Save to File

put_diagram(workflow, output = "file", file = "workflow.md")

Interactive Sandbox

Experiment without creating files:

run_sandbox()  # Opens Shiny app

Quick Reference

# Core functions
put(path)                    # Extract annotations
put_diagram(workflow)        # Generate Mermaid diagram
put_auto(path)               # Auto-detect workflow (no annotations)
put_generate(path)           # Generate annotation suggestions

# Useful options
put("./", recursive = TRUE)  # Include subdirectories
put_diagram(wf, theme = "github", direction = "LR")
put_diagram(wf, show_artifacts = FALSE)  # Hide data files

Need help? Run ?put or ?put_diagram for full documentation.

See Also

Guide Description
Annotation Guide Complete syntax reference
Features Tour Auto-detection, themes, logging
API Reference Function documentation
Showcase Real-world examples
Quick Reference At-a-glance reference card
Troubleshooting Common issues and solutions
AI Integration MCP/ACP integration guide