PlantUML ASCII Art Diagram Generator Overview

Create text-based ASCII art diagrams using PlantUML. Perfect for documentation in terminal environments, README files, emails, or any scenario where graphical diagrams aren't suitable.

What is PlantUML ASCII Art?

PlantUML can generate diagrams as plain text (ASCII art) instead of images. This is useful for:

Terminal-based workflows Git commits/PRs without image support Documentation that needs to be version-controlled Environments where graphical tools aren't available Installation

macOS

brew install plantuml

Linux (varies by distro)

sudo apt-get install plantuml # Ubuntu/Debian sudo yum install plantuml # RHEL/CentOS

Or download JAR directly

wget https://github.com/plantuml/plantuml/releases/download/v1.2024.0/plantuml-1.2024.0.jar

Output Formats Flag Format Description -txt ASCII Pure ASCII characters -utxt Unicode ASCII Enhanced with box-drawing characters Basic Workflow 1. Create PlantUML Diagram File @startuml participant Bob actor Alice

Bob -> Alice : hello Alice -> Bob : Is it ok? @enduml

Generate ASCII Art

Standard ASCII output

plantuml -txt diagram.puml

Unicode-enhanced output (better looking)

plantuml -utxt diagram.puml

Using JAR directly

java -jar plantuml.jar -txt diagram.puml java -jar plantuml.jar -utxt diagram.puml

View Output

Output is saved as diagram.atxt (ASCII) or diagram.utxt (Unicode).

Diagram Types Supported Sequence Diagram @startuml actor User participant "Web App" as App database "Database" as DB

User -> App : Login Request App -> DB : Validate Credentials DB --> App : User Data App --> User : Auth Token @enduml

Class Diagram @startuml class User { +id: int +name: string +email: string +login(): bool }

class Order { +id: int +total: float +items: List +calculateTotal(): float }

User "1" -- "*" Order : places @enduml

Activity Diagram @startuml start :Initialize; if (Is Valid?) then (yes) :Process Data; :Save Result; else (no) :Log Error; stop endif :Complete; stop @enduml

State Diagram @startuml [] --> Idle Idle --> Processing : start Processing --> Success : complete Processing --> Error : fail Success --> [] Error --> Idle : retry @enduml

Component Diagram @startuml [Client] as client [API Gateway] as gateway [Service A] as svcA [Service B] as svcB [Database] as db

client --> gateway gateway --> svcA gateway --> svcB svcA --> db svcB --> db @enduml

Use Case Diagram @startuml actor "User" as user actor "Admin" as admin

rectangle "System" { user -- (Login) user -- (View Profile) user -- (Update Settings) admin -- (Manage Users) admin -- (Configure System) } @enduml

Deployment Diagram @startuml actor "User" as user node "Load Balancer" as lb node "Web Server 1" as ws1 node "Web Server 2" as ws2 database "Primary DB" as db1 database "Replica DB" as db2

user --> lb lb --> ws1 lb --> ws2 ws1 --> db1 ws2 --> db1 db1 --> db2 : replicate @enduml

Command-Line Options

Specify output directory

plantuml -txt -o ./output diagram.puml

Process all files in directory

plantuml -txt ./diagrams/

Include dot files (hidden files)

plantuml -txt -includeDot diagrams/

Verbose output

plantuml -txt -v diagram.puml

Specify charset

plantuml -txt -charset UTF-8 diagram.puml

Ant Task Integration

Tips for Better ASCII Diagrams Keep it simple: Complex diagrams don't render well in ASCII Short labels: Long text breaks ASCII alignment Use Unicode (-utxt): Better visual quality with box-drawing chars Test before sharing: Verify in terminal with fixed-width font Consider alternatives: For complex diagrams, use Mermaid.js or graphviz Example Output Comparison

Standard ASCII (-txt):

 ,---.          ,---.
 |Bob|          |Alice|
 `---'          `---'
  |   hello      |
  |------------->|
  |              |
  |  Is it ok?   |
  |<-------------|
  |              |

Unicode ASCII (-utxt):

┌─────┐ ┌─────┐ │ Bob │ │Alice│ └─────┘ └─────┘ │ hello │ │─────────────>│ │ │ │ Is it ok? │ │<─────────────│ │ │

Quick Reference

Create sequence diagram in ASCII

cat > seq.puml << 'EOF' @startuml Alice -> Bob: Request Bob --> Alice: Response @enduml EOF

plantuml -txt seq.puml cat seq.atxt

Create with Unicode

plantuml -utxt seq.puml cat seq.utxt

Troubleshooting

Problem: Garbled Unicode characters

Solution: Ensure terminal supports UTF-8 and has proper font

Problem: Diagram looks misaligned

Solution: Use fixed-width font (Courier, Monaco, Consolas)

Problem: Command not found

Solution: Install PlantUML or use Java JAR directly

Problem: Output file not created

Solution: Check file permissions, ensure PlantUML has write access

plantuml-ascii

安装