aa2img

Convert ASCII/Unicode diagrams into clean SVG and PNG images

Features • Installation • Usage • Diagram Syntax • Themes

aa2img parses text-based box diagrams and renders them as themed images. It is useful for docs, README files, and architecture notes where you want to keep diagrams editable as plain text.

• Parses both Unicode and ASCII box-drawing styles (┌─┐ │ └─┘ and +--+ | | +--+)
• Detects section separators (├──┤) inside boxes
• Detects nested parent-child box structures
• Renders right-side annotations in ← note format
• Handles full-width characters, including Japanese labels
• Supports SVG and PNG output
• Ships with 4 built-in themes: default, blueprint, monochrome, modern
• Supports vertical label alignment: top, center, bottom

• Ruby 3.2+
• ImageMagick (required only for PNG output)

# macOS
brew install imagemagick

# Ubuntu / Debian
sudo apt install imagemagick

gem "aa2img", github: "ydah/aa2img"

After the gem is published to RubyGems, you can also install it with:

gem install aa2img

1. Create a text diagram file:

┌────────────────────────────┐
│        API Gateway         │
├────────────────────────────┤
│        Application         │
│  ┌──────────────────────┐  │
│  │       Database       │  │
│  └──────────────────────┘  │
└────────────────────────────┘

2. Convert to SVG:

aa2img convert diagram.txt output.svg

3. Convert to PNG:

aa2img convert diagram.txt output.png --scale 3

Notes:

• Use - as INPUT_FILE to read from stdin.
• Output format is inferred from OUTPUT_FILE extension (.svg or .png).

# Read from stdin
cat diagram.txt | aa2img convert - output.svg

# Use blueprint theme
aa2img convert diagram.txt blueprint.svg --theme blueprint

# Use custom theme file
aa2img convert diagram.txt custom.svg --theme ./themes/my-theme.yml

# Center label alignment
aa2img convert diagram.txt centered.svg --valign center

require "aa2img"

aa = <<~AA
  ┌──────┐
  │ Test │
  └──────┘
AA

# Get SVG string
svg = AA2img.convert(aa, format: :svg, theme: "default", valign: :center)

# Write to file (format inferred from extension)
AA2img.convert_to_file(aa, "diagram.png", theme: "monochrome", scale: 2, valign: :top)

Unicode:

┌──────┐
│ API  │
└──────┘

ASCII:

+------+
| API  |
+------+

┌────────────────┐
│ Presentation   │
├────────────────┤
│ Application    │
├────────────────┤
│ Infrastructure │
└────────────────┘

┌──────────┐  ← user input
│  REPL    │
└──────────┘

Built-in themes:

• default: balanced light theme
• blueprint: deep-blue blueprint-like style
• monochrome: print-friendly grayscale style
• modern: clean, rounded, modern UI style

aa2img themes

CLI also accepts a YAML path for custom themes:

aa2img convert diagram.txt output.svg --theme ./themes/my-theme.yml

You can also pass a custom theme hash from Ruby:

custom_theme = {
  "background_color" => "#ffffff",
  "box_fill" => "#f8fafc",
  "box_stroke" => "#334155",
  "text_color" => "#0f172a",
  "font_family" => "'Noto Sans JP', sans-serif"
}

svg = AA2img.convert(aa, format: :svg, theme: custom_theme)

• Current parser behavior is optimized for box/layer diagrams.
• Annotation detection currently supports right-side ← markers.
• preview --format is reserved for future expansion; current output is tree-style.

git clone https://github.com/ydah/aa2img.git
cd aa2img
bin/setup
bundle exec rspec

Run the example script:

bundle exec ruby examples/basic_usage.rb

Issues and pull requests are welcome at https://github.com/ydah/aa2img.

MIT License