generate-workflow-diagram

Generate a themed Mermaid flowchart diagram from putior workflow data and embed it in documentation.

When to Use

• After annotating source files and ready to produce the visual diagram
• Regenerating a diagram after workflow changes
• Switching themes or output formats for different audiences
• Embedding workflow diagrams in README, Quarto, or R Markdown documents

Inputs

• Required: Workflow data from put(), put_auto(), or put_merge()
• Optional: Theme name (default: "light"; options: light, dark, auto, minimal, github, viridis, magma, plasma, cividis)
• Optional: Output target: console, file path, clipboard, or raw string
• Optional: Interactive features: show_source_info, enable_clicks

Procedure

Step 1: Extract Workflow Data

Obtain workflow data from one of three sources.

library(putior)

# From manual annotations
workflow <- put("./src/")

# From manual annotations, excluding specific files
workflow <- put("./src/", exclude = c("build-workflow\\.R$", "test_"))

# From auto-detection only
workflow <- put_auto("./src/")

# From merged (manual + auto)
workflow <- put_merge("./src/", merge_strategy = "supplement")

The workflow data frame may include a node_type column from annotations. Node types control Mermaid shapes:

| node_type | Mermaid Shape | Use Case | |---|---|---| | "input" | Stadium ([...]) | Data sources, configuration files | | "output" | Subroutine [[...]] | Generated artifacts, reports | | "process" | Rectangle [...] | Processing steps (default) | | "decision" | Diamond {...} | Conditional logic, branching | | "start" / "end" | Stadium ([...]) | Entry/terminal nodes |

Each node_type also receives a corresponding CSS class (e.g., class nodeId input;) for theme-based styling.

Expected: A data frame with at least one row, containing id, label, and optionally input, output, source_file, node_type columns.

On failure: If the data frame is empty, no annotations or patterns were found. Run analyze-codebase-workflow first, or check that annotations are syntactically valid with put("./src/", validate = TRUE).

Step 2: Select Theme and Options

Choose a theme appropriate for the target audience.

List all available themes:

get_diagram_themes()

Standard themes

• "light" — Default, bright colors
• "dark" — For dark mode environments
• "auto" — GitHub-adaptive with solid colors
• "minimal" — Grayscale, print-friendly
• "github" — Optimized for GitHub README files

Colorblind-safe themes (viridis family)

• "viridis" — Purple→Blue→Green→Yellow, general accessibility
• "magma" — Purple→Red→Yellow, high contrast for print
• "plasma" — Purple→Pink→Orange→Yellow, presentations
• "cividis" — Blue→Gray→Yellow, maximum accessibility (no red-green)

Additional parameters:

• direction: Diagram flow direction — "TD" (top-down, default), "LR" (left-right), "RL", "BT"
• show_artifacts: TRUE/FALSE — show artifact nodes (files, data); can be noisy for large workflows (e.g., 16+ extra nodes)
• show_workflow_boundaries: TRUE/FALSE — wrap each source file's nodes in a Mermaid subgraph
• source_info_style: How source file info is displayed on nodes (e.g., as subtitle)
• node_labels: Format for node label text

Expected: Theme names printed. Select one based on context.

On failure: If a theme name is not recognized, put_diagram() falls back to "light". Check spelling.

Step 3: Custom Palette with put_theme() (Optional)

If the 9 built-in themes don't match your project's palette, create a custom theme with put_theme().

# Create custom palette — unspecified types inherit from base theme
cyberpunk <- put_theme(
  base = "dark",
  input    = c(fill = "#1a1a2e", stroke = "#00ff88", color = "#00ff88"),
  process  = c(fill = "#16213e", stroke = "#44ddff", color = "#44ddff"),
  output   = c(fill = "#0f3460", stroke = "#ff3366", color = "#ff3366"),
  decision = c(fill = "#1a1a2e", stroke = "#ffaa33", color = "#ffaa33")
)

# Use the palette parameter (overrides theme when provided)
mermaid_content <- put_diagram(workflow, palette = cyberpunk, output = "raw")
writeLines(mermaid_content, "workflow.mmd")

put_theme() accepts input, process, output, decision, artifact, start, and end node types. Each takes a named vector c(fill = "#hex", stroke = "#hex", color = "#hex"). Unset types inherit from the base theme.

Expected: Mermaid output with your custom classDef lines. Node shapes from node_type are preserved; only colors change. All node types use stroke-width:2px — override not currently supported via put_theme().

On failure: If the palette object is not a putior_theme class, put_diagram() raises a descriptive error. Ensure you pass the return value of put_theme(), not a raw list.

Fallback — manual classDef replacement: For fine-grained control beyond what put_theme() offers (e.g., per-type stroke widths), generate with a base theme and replace classDef lines manually:

mermaid_content <- put_diagram(workflow, theme = "dark", output = "raw")
lines <- strsplit(mermaid_content, "\n")[[1]]
lines <- lines[!grepl("^\\s*classDef ", lines)]
custom_defs <- c("  classDef input fill:#1a1a2e,stroke:#00ff88,stroke-width:3px,color:#00ff88")
mermaid_content <- paste(c(lines, custom_defs), collapse = "\n")

Step 4: Generate Mermaid Output

Produce the diagram in the desired output mode.

# Print to console (default)
cat(put_diagram(workflow, theme = "github"))

# Save to file
writeLines(put_diagram(workflow, theme = "github"), "docs/workflow.md")

# Get raw string for embedding
mermaid_code <- put_diagram(workflow, output = "raw", theme = "github")

# With source file info (shows which file each node comes from)
cat(put_diagram(workflow, theme = "github", show_source_info = TRUE))

# With clickable nodes (for VS Code, RStudio, or file:// protocol)
cat(put_diagram(workflow,
  theme = "github",
  enable_clicks = TRUE,
  click_protocol = "vscode"  # or "rstudio", "file"
))

# Full-featured
cat(put_diagram(workflow,
  theme = "viridis",
  show_source_info = TRUE,
  enable_clicks = TRUE,
  click_protocol = "vscode"
))

Expected: Valid Mermaid code starting with flowchart TD (or LR depending on direction). Nodes are connected by arrows showing data flow.

On failure: If the output is flowchart TD with no nodes, the workflow data frame is empty. If connections are missing, check that output filenames match input filenames across nodes.

Step 5: Embed in Target Document

Insert the diagram into the appropriate documentation format.

GitHub README (```mermaid code fence):

## Workflow

```mermaid
flowchart TD
  A["Extract Data"] --> B["Transform"]
  B --> C["Load"]
```

Quarto document (native mermaid chunk via knit_child):

# Chunk 1: Generate code (visible, foldable)
workflow <- put("./src/")
mermaid_code <- put_diagram(workflow, output = "raw", theme = "github")

# Chunk 2: Output as native mermaid chunk (hidden)
#| output: asis
#| echo: false
mermaid_chunk <- paste0("```{mermaid}\n", mermaid_code, "\n```")
cat(knitr::knit_child(text = mermaid_chunk, quiet = TRUE))

R Markdown (with mermaid.js CDN or DiagrammeR):

DiagrammeR::mermaid(put_diagram(workflow, output = "raw"))

Expected: Diagram renders correctly in the target format. GitHub renders mermaid code fences natively.

On failure: If GitHub doesn't render the diagram, ensure the code fence uses exactly ```mermaid (no extra attributes). For Quarto, ensure the knit_child() approach is used since direct variable interpolation in {mermaid} chunks is not supported.

Validation

• [ ] put_diagram() produces valid Mermaid code (starts with flowchart)
• [ ] All expected nodes appear in the diagram
• [ ] Data flow connections (arrows) are present between connected nodes
• [ ] Selected theme is applied (check init block in output for theme-specific colors)
• [ ] Diagram renders correctly in the target format (GitHub, Quarto, etc.)

Common Pitfalls

• Empty diagrams: Usually means put() returned no rows. Check annotations exist and are syntactically valid.
• All nodes disconnected: Output filenames must exactly match input filenames (including extension) for putior to draw connections. data.csv and Data.csv are different.
• Theme not visible on GitHub: GitHub's mermaid renderer has limited theme support. The "github" theme is specifically designed for GitHub rendering. The %%{init:...}%% theme block may be ignored by some renderers.
• Quarto mermaid variable interpolation: Quarto's {mermaid} chunks don't support R variables directly. Use the knit_child() technique described in Step 5.
• Clickable nodes not working: Click directives require a renderer that supports Mermaid interaction events. GitHub's static renderer does not support clicks. Use a local Mermaid renderer or the putior Shiny sandbox.
• Self-referential meta-pipeline files: Scanning a directory that includes the build script generating the diagram causes duplicate subgraph IDs and Mermaid errors. Use the exclude parameter to skip them at scan time:

  workflow <- put("./src/", exclude = c("build-workflow\\.R$", "build-workflow\\.js$"))
  

• show_artifacts = TRUE too noisy: Large projects may generate many artifact nodes (10–20+), cluttering the diagram. Use show_artifacts = FALSE and rely on node_type annotations to mark key inputs/outputs explicitly.

Related Skills

• annotate-source-files — prerequisite: files must be annotated before diagram generation
• analyze-codebase-workflow — auto-detection can supplement manual annotations
• setup-putior-ci — automate diagram regeneration in CI/CD
• create-quarto-report — embed diagrams in Quarto reports
• build-pkgdown-site — embed diagrams in pkgdown documentation sites
• restore-diagram-legibility — when a generated diagram outgrows its canvas and labels drop below legibility