Quick Reference

Quickest Start

put("./src/") |> put_diagram()

Annotation Syntax

# put id:"node_id", label:"Description", node_type:"process", input:"in.csv", output:"out.csv"

Field	Required	Default	Description
`label`	Yes	-	Human-readable name
`id`	No	UUID	Unique identifier
`node_type`	No	`process`	`input`, `process`, `output`, `decision`, `start`, `end`
`input`	No	-	Comma-separated input files
`output`	No	filename	Comma-separated output files

Multiline: End lines with \ for continuation.

Comment Prefixes

Find your language:

# put  →  R, Python, Shell, Julia, Ruby, YAML, Perl, TOML, Dockerfile, Makefile
-- put →  SQL, Lua, Haskell
// put →  JavaScript, TypeScript, Go, Rust, Java, C, C++, Swift, Kotlin, C#, PHP, Scala, WGSL
% put  →  MATLAB, LaTeX
* put  →  Block comments (/* */ and /** */) in all // languages

Core Functions

Function	Purpose	Example
`put()`	Extract annotations	`put("./src/")`
`put_diagram()`	Generate Mermaid	`put_diagram(workflow)`
`put_auto()`	Auto-detect workflow	`put_auto("./src/")`
`put_generate()`	Suggest annotations	`put_generate("./src/")`
`put_merge()`	Merge manual + auto	`put_merge("./src/")`

Key Parameters

put() and scan functions:

put(path, pattern, recursive = TRUE, include_line_numbers = FALSE,
    validate = TRUE, exclude = NULL, log_level = NULL)

put_diagram():

put_diagram(workflow, output = "console", file = NULL, direction = "TD",
    theme = "github", show_artifacts = FALSE, show_source_info = FALSE,
    enable_clicks = FALSE, click_protocol = "vscode", palette = NULL,
    style_nodes = TRUE, node_labels = "label", title = NULL)

put_theme():

put_theme(base = "light", input = NULL, process = NULL, output = NULL,
    decision = NULL, artifact = NULL, start = NULL, end = NULL)
# Each node type: c(fill = "#hex", stroke = "#hex", color = "#hex")

Common Patterns

Basic

put("./src/") |> put_diagram()

Customize

put_diagram(wf, theme = "dark", direction = "LR")
put_diagram(wf, show_artifacts = FALSE)       # Hide data files
put_diagram(wf, show_source_info = TRUE)      # Show file info
put_diagram(wf, palette = put_theme(base = "dark", input = c(fill = "#1a5276")))

Save

put_diagram(wf, output = "file", file = "workflow.md")
put_diagram(wf, output = "clipboard")
mermaid_code <- put_diagram(wf, output = "raw")

Exclude files

put("./src/", exclude = "test")
put_auto("./", exclude = c("vendor", "fixture"))

Debug

put("./", log_level = "DEBUG")

Configuration & Utilities

Function	Purpose	Example
`get_comment_prefix()`	Comment prefix for extension	`get_comment_prefix("sql")` → `"--"`
`get_supported_extensions()`	All supported extensions	`get_supported_extensions()`
`list_supported_languages()`	Supported languages	`list_supported_languages(detection_only = TRUE)`
`get_detection_patterns()`	Auto-detection patterns	`get_detection_patterns("r", type = "input")`
`get_diagram_themes()`	Available themes	`get_diagram_themes()`
`is_valid_put_annotation()`	Validate syntax	`is_valid_put_annotation('# put label:"X"')`
`set_putior_log_level()`	Set logging level	`set_putior_log_level("DEBUG")`
`run_sandbox()`	Launch Shiny sandbox	`run_sandbox()`

Themes and Direction

Theme	Use Case
`light`	Bright colors (default)
`dark`	Dark mode UIs
`minimal`	Print-friendly, grayscale
`github`	README files
`viridis`	Colorblind-safe (purple-blue-green-yellow)
`magma`	Colorblind-safe warm (purple-red-yellow)
`plasma`	Colorblind-safe vibrant (purple-pink-yellow)
`cividis`	Maximum accessibility (blue-yellow only)

Directions: TD (default), LR, BT, RL

Node Types

Type	Shape	Use For
`input`	Stadium	Data loading
`process`	Rectangle	Transformations (default)
`output`	Subroutine	Reports, exports
`decision`	Diamond	Conditional logic
`start`	Stadium	Workflow entry point
`end`	Stadium	Workflow exit point
`artifact`	Cylinder	Data files (auto-created)

flowchart TD
    load(["input"])
    transform["process"]
    export[["output"]]
    check{"decision"}

    %% Connections
    load --> transform
    transform --> export
    transform --> check

    %% 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 transform processStyle
    classDef outputStyle fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#15803d
    class export outputStyle
    classDef decisionStyle fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#92400e
    class check decisionStyle

Guide	Description
Quick Start	First diagram in 2 minutes
Annotation Guide	Complete syntax reference
Features Tour	Auto-detection, themes, logging
API Reference	Function documentation
Showcase	Real-world examples
Troubleshooting	Common issues and solutions
AI Integration	MCP/ACP integration guide