| name | plantuml-ascii |
| description | Generate ASCII art diagrams using PlantUML text mode. Use when user asks to create ASCII diagrams, text-based diagrams, terminal-friendly diagrams, or mentions plantuml ascii, text diagram, ascii art diagram. Supports: Converting PlantUML diagrams to ASCII art, Creating sequence diagrams, class diagrams, flowcharts in ASCII format, Generating Unicode-enhanced ASCII art with -utxt flag |
| license | MIT |
| allowed-tools | Bash, Write, Read |
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
brew install plantuml
sudo apt-get install plantuml
sudo yum install plantuml
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
2. Generate ASCII Art
plantuml -txt diagram.puml
plantuml -utxt diagram.puml
java -jar plantuml.jar -txt diagram.puml
java -jar plantuml.jar -utxt diagram.puml
3. 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
plantuml -txt -o ./output diagram.puml
plantuml -txt ./diagrams/
plantuml -txt -includeDot diagrams/
plantuml -txt -v diagram.puml
plantuml -txt -charset UTF-8 diagram.puml
Ant Task Integration
<target name="generate-ascii">
<plantuml dir="./src" format="txt" />
</target>
<target name="generate-unicode-ascii">
<plantuml dir="./src" format="utxt" />
</target>
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
cat > seq.puml << 'EOF'
@startuml
Alice -> Bob: Request
Bob --> Alice: Response
@enduml
EOF
plantuml -txt seq.puml
cat seq.atxt
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
