PlantUML Converter

Convert PlantUML (.puml) files to image formats (PNG, SVG, PDF).

When to Use

Use this skill when user requests:

• "convert puml", "render PlantUML", "generate image"
• "puml to png", "puml to svg"
• "export diagram", "render diagram"
• Any request involving converting .puml files to images

Prerequisites

• Java: JRE 8+ (JDK 11+ recommended)
• PlantUML.jar: Rendering engine (auto-download available)

Auto-Download

If

plantuml.jar

init-config

• Source: GitHub Releases
• Location:

  <skill_dir>/lib/plantuml.jar

• Size: ~8MB

Version selection based on Java:

The download uses:

• Linux/Mac:

  curl

  or

  wget

• Windows: PowerShell or

  curl

Compatibility

Java Version Requirements

Known Compatibility Issues

UnsupportedClassVersionError

NoClassDefFoundError

-charset UTF-8

Version Check

The

check-env

1. Java installation and version (must be 8+)
2. PlantUML.jar existence
3. PlantUML version (optional)
4. Compatibility between Java and PlantUML

Configuration

Option 1: Config File (Recommended)

Edit

plantuml-config.json

<skill_dir>/plantuml-config.json

{
  "plantumlJar": "C:/tools/plantuml/plantuml.jar",
  "javaPath": "C:/Program Files/Java/jdk-17/bin/java.exe"
}

Option 2: Environment Variables

• PLANTUML_LIB

  : Full path to plantuml.jar

• JAVA_HOME

  : Java installation directory

Priority

CLI arguments > Config file > Environment variables > System default java

Usage

Windows

Step 1: Initialize Config

%SKILL_DIR%\scripts\init-config.bat

Step 2: Check Environment

%SKILL_DIR%\scripts\check-env.bat

Step 3: Convert Files

REM Single file
%SKILL_DIR%\scripts\convert.bat input.puml

REM Specify format
%SKILL_DIR%\scripts\convert.bat input.puml -f svg
%SKILL_DIR%\scripts\convert.bat input.puml -f png
%SKILL_DIR%\scripts\convert.bat input.puml -f pdf

REM Specify output
%SKILL_DIR%\scripts\convert.bat input.puml -o output.png

REM Batch convert
%SKILL_DIR%\scripts\convert.bat ./diagrams/ -r

Linux/Mac

Step 1: Initialize Config

bash <skill_dir>/scripts/init-config.sh

Step 2: Check Environment

bash <skill_dir>/scripts/check-env.sh

Step 3: Convert Files

# Single file
bash <skill_dir>/scripts/convert.sh input.puml

# Specify format
bash <skill_dir>/scripts/convert.sh input.puml -f svg
bash <skill_dir>/scripts/convert.sh input.puml -f png
bash <skill_dir>/scripts/convert.sh input.puml -f pdf

# Specify output
bash <skill_dir>/scripts/convert.sh input.puml -o output.png

# Batch convert
bash <skill_dir>/scripts/convert.sh ./diagrams/ -r

Direct Command (No Script)

When paths are known, call directly:

REM Windows
java -jar C:\path\to\plantuml.jar -tpng diagram.puml

REM Linux/Mac
java -jar /path/to/plantuml.jar -tpng diagram.puml

Command Arguments

input

-f FORMAT

-o OUTPUT

-t THEME

-D KEY=VALUE

-r

--config PATH

--plantuml PATH

--java PATH

Default output behavior: Without

-o

diagram.puml  →  diagram.png
/path/to/arch.puml  →  /path/to/arch.png

Character Encoding

All conversions use

-charset UTF-8

• CJK characters (Chinese, Japanese, Korean)
• Emoji and special symbols
• Unicode text in diagrams

If you still see garbled text, ensure your .puml file is saved with UTF-8 encoding.

PlantUML Examples

Sequence Diagram

@startuml
title User Login Flow

actor User
participant "Frontend" as FE
participant "Backend" as BE
database "Database" as DB

User -> FE: Enter credentials
FE -> BE: POST /api/login
BE -> DB: Query user info
DB --> BE: Return user data
BE --> FE: Return JWT Token
FE --> User: Login success, redirect

@enduml

Class Diagram

@startuml
title Class Diagram Example

class User {
  - id: Long
  - username: String
  - password: String
  - email: String
  + login(): Boolean
  + register(): Boolean
  + changePassword(): void
}

class Order {
  - orderNo: String
  - amount: Double
  - status: Enum
  + create(): void
  + cancel(): void
}

class Product {
  - productId: Long
  - name: String
  - price: Double
  - stock: Integer
}

User "1" -- "*" Order : has >
Order "*" -- "*" Product : contains >

@enduml

Activity Diagram

@startuml
title Order Processing Flow

start
:User submits order;
if (Stock available?) then (yes)
  :Deduct stock;
  :Create order;
  if (Payment success?) then (yes)
    :Ship goods;
    :Complete order;
  else (no)
    :Cancel order;
    :Restore stock;
    :Notify payment failure;
  endif
else (no)
  :Notify out of stock;
endif
stop

@enduml

Use Case Diagram

@startuml
title E-Commerce System Use Cases

left to right direction
actor User
actor Admin

rectangle "E-Commerce System" {
  usecase "Browse Products" as UC1
  usecase "Search Products" as UC2
  usecase "Add to Cart" as UC3
  usecase "Place Order" as UC4
  usecase "Payment" as UC5
  usecase "View Orders" as UC6
  usecase "Manage Products" as UC7
  usecase "Manage Orders" as UC8
  usecase "Manage Users" as UC9
}

User --> UC1
User --> UC2
User --> UC3
User --> UC4
User --> UC5
User --> UC6
Admin --> UC7
Admin --> UC8
Admin --> UC9

@enduml

Component Diagram

@startuml
title System Architecture

package "Frontend" {
  [Web App] as Web
  [Mobile App] as Mobile
}

package "Backend Services" {
  [API Gateway] as Gateway
  [User Service] as UserService
  [Order Service] as OrderService
  [Product Service] as ProductService
  [Payment Service] as PaymentService
}

database "Database" {
  [MySQL] as DB
  [Redis] as Cache
}

Web --> Gateway
Mobile --> Gateway
Gateway --> UserService
Gateway --> OrderService
Gateway --> ProductService
Gateway --> PaymentService
UserService --> DB
OrderService --> DB
ProductService --> DB
PaymentService --> DB
UserService --> Cache

@enduml

State Diagram

@startuml
title Order State Transitions

[*] --> Pending: Create order
Pending --> Paid: Payment success
Pending --> Cancelled: Timeout/user cancel
Paid --> Shipping: Merchant ships
Shipping --> Delivered: User confirms receipt
Delivered --> Completed: Auto complete
Delivered --> Refunding: Request refund
Refunding --> Refunded: Refund success
Refunding --> Delivered: Cancel refund
Cancelled --> [*]
Completed --> [*]
Refunded --> [*]

@enduml

Conversion Examples

REM Windows - Basic conversion
convert.bat architecture.puml

REM Windows - SVG format
convert.bat architecture.puml -f svg

REM Windows - Custom theme
convert.bat diagram.puml -t blueprint

REM Windows - Batch convert
convert.bat ./docs/ -r -f svg

# Linux/Mac - Basic conversion
bash convert.sh architecture.puml

# Linux/Mac - SVG format
bash convert.sh architecture.puml -f svg

# Linux/Mac - Custom theme
bash convert.sh diagram.puml -t blueprint

# Linux/Mac - Batch convert
bash convert.sh ./docs/ -r -f svg

Troubleshooting

java: command not found

plantuml.jar not found

Syntax error

Permission denied

Script List

init-config.bat

init-config.sh

check-env.bat

check-env.sh

convert.bat

convert.sh