ASCII Markdown Svgbob

Use this skill to convert ASCII/Unicode diagrams embedded in Markdown fenced code blocks into SVG files using svgbob, then replace those code blocks with Markdown image links.

Prerequisites

The target machine must have a svgbob executable available on PATH. Acceptable executable names are svgbob, svgbob_cli, svgbob.exe, or svgbob_cli.exe.

If svgbob is missing, tell the user to install it, for example:

cargo install svgbob_cli

Do not require Python unless you choose the Python script. This skill includes equivalent Python, Bash, and PowerShell entry points.

Script Selection

Choose the script that best fits the environment:

• Linux/macOS with Bash: scripts/replace_ascii_diagrams.sh
• Windows with Python available: python -X utf8 scripts/replace_ascii_diagrams.py
• Windows PowerShell or PowerShell Core, only after verifying it parses in the local shell: scripts/Replace-AsciiDiagrams.ps1
• Python environment already available: scripts/replace_ascii_diagrams.py

Prefer Bash on Unix-like systems. On Windows, prefer the Python entry point with -X utf8 unless the user specifically wants to avoid Python and the PowerShell script has already been dry-run successfully. This avoids Windows console/codepage hangs when rendering Unicode box-drawing diagrams.

Supported Markdown Blocks

Treat these fenced code block info strings as diagram candidates:

ascii
ascii-diagram
asciidiagram
diagram
svgbob
bob
text-diagram
box
flow

Also allow a title after the language word. The title becomes the image alt text:

+---------+ +----------+

+---------+ +----------+

Replace with a Markdown image link such as:

![Authorization callback flow](assets/readme-diagram-1-a1b2c3d4.svg)

Avoid converting normal source code blocks such as python, bash, json, yaml, mermaid, or plantuml.

Recommended Workflow

1. Inspect the Markdown files first so you understand what will be modified.
2. Run a dry run against the target files or directory.
3. Run the replacement script.
4. Review the Markdown diff and generated SVG files.

Bash examples:

bash scripts/replace_ascii_diagrams.sh --dry-run README.md
bash scripts/replace_ascii_diagrams.sh --recursive docs
bash scripts/replace_ascii_diagrams.sh --recursive --keep-source .

PowerShell examples:

pwsh scripts/Replace-AsciiDiagrams.ps1 -DryRun README.md
pwsh scripts/Replace-AsciiDiagrams.ps1 -Recursive docs
pwsh scripts/Replace-AsciiDiagrams.ps1 -Recursive -KeepSource .

Python examples:

python scripts/replace_ascii_diagrams.py --dry-run README.md
python scripts/replace_ascii_diagrams.py --recursive docs
python scripts/replace_ascii_diagrams.py --recursive --keep-source .

Windows Python examples:

python -X utf8 scripts/replace_ascii_diagrams.py --dry-run README.md
python -X utf8 scripts/replace_ascii_diagrams.py README.md

Options

All three scripts support the same core options:

• --recursive or -Recursive: recursively process Markdown files in directories.
• --dry-run or -DryRun: report replacements without writing files.
• --assets-dir or -AssetsDir : choose the asset directory name beside each Markdown file. Default: assets.
• --force or -Force: overwrite an existing generated SVG when content differs.
• --keep-source or -KeepSource: keep the original ASCII diagram in an HTML comment after the image link.

Generated SVG filenames include the Markdown stem, diagram index, and a hash of the diagram text to reduce collisions.

Safety Rules

Before editing files, run dry-run unless the user explicitly asks for direct modification. Do not convert unlabeled code blocks aggressively when that would risk changing logs, shell output, tables, or source code. After modifications, summarize which Markdown files changed and where generated SVG files were written.