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
← noteformat - Handles full-width characters, including Japanese labels
- Supports
SVGandPNGoutput - 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 imagemagickgem "aa2img", github: "ydah/aa2img"After the gem is published to RubyGems, you can also install it with:
gem install aa2img- Create a text diagram file:
┌────────────────────────────┐
│ API Gateway │
├────────────────────────────┤
│ Application │
│ ┌──────────────────────┐ │
│ │ Database │ │
│ └──────────────────────┘ │
└────────────────────────────┘- Convert to SVG:
aa2img convert diagram.txt output.svg- Convert to PNG:
aa2img convert diagram.txt output.png --scale 3| Command | Description |
|---|---|
aa2img convert INPUT_FILE OUTPUT_FILE |
Convert text diagram to image (format inferred from extension) |
aa2img themes |
List available themes |
aa2img preview INPUT_FILE |
Show parsed AST tree for debugging |
aa2img version |
Show version |
| Option | Description |
|---|---|
--theme NAME_OR_PATH |
Built-in theme name (default, blueprint, monochrome, modern) or YAML file path |
--scale N |
Scale factor for PNG output (default: 2) |
--valign POS |
Vertical label alignment (top, center, bottom) |
Notes:
- Use
-asINPUT_FILEto read from stdin. - Output format is inferred from
OUTPUT_FILEextension (.svgor.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 centerrequire "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 themeblueprint: deep-blue blueprint-like stylemonochrome: print-friendly grayscale stylemodern: clean, rounded, modern UI style
aa2img themesCLI also accepts a YAML path for custom themes:
aa2img convert diagram.txt output.svg --theme ./themes/my-theme.ymlYou 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 --formatis reserved for future expansion; current output is tree-style.
git clone https://github.com/ydah/aa2img.git
cd aa2img
bin/setup
bundle exec rspecRun the example script:
bundle exec ruby examples/basic_usage.rbIssues and pull requests are welcome at https://github.com/ydah/aa2img.