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_70632c81_125c_4742_99e9_6c80835453d1["Extract"]
    node_82a58bb2_28dd_4a52_9975_757b9a317ae7["Transform"]
    node_851df76e_caad_4704_8ad6_ebfb8b9781d1["Load"]

    %% Connections
    node_70632c81_125c_4742_99e9_6c80835453d1 --> node_82a58bb2_28dd_4a52_9975_757b9a317ae7
    node_82a58bb2_28dd_4a52_9975_757b9a317ae7 --> node_851df76e_caad_4704_8ad6_ebfb8b9781d1

---

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