~/guides/readme-banner · plain text that ships

README ASCII banner from an image

A README banner that is still just characters: no CDN, no broken image badge, no upload to a third-party converter. Convert the logo locally, paste the text, ship the pull request.

Open README preset more use cases
[ why_ascii_in_readme ]

Why plain text beats a hosted logo

Git hosts render fenced code blocks everywhere. An ASCII banner travels with the repo, survives dark mode, and never depends on an external image URL. Semaphore turns your existing mark into that text without sending the file anywhere.

[ steps ]

Four steps to a paste-ready banner

  1. 01 open a README-friendly preset

    Start with blocks or standard at about 80 columns. Wide logos stay legible; dense photos belong in braille mode instead.

  2. 02 drop the image locally

    PNG with transparency, JPG export, or a simple monochrome mark all work. The tool samples pixels on a local canvas; production CSP is connect-src 'none'.

  3. 03 tune for monochrome Markdown

    Bump contrast if edges look soft. Invert if the subject is dark on light. Keep columns low enough that a phone-width README still wraps as one block of text, not a horizontal scroll marathon.

  4. 04 paste into a fenced code block

    Copy plain text from the tool and drop it into README.md. The fence is load-bearing: without it Markdown collapses the runs of spaces that carry the shading, and the mark falls apart. Tag it text so no syntax highlighter tries to colour the glyphs.

    ```text
████▓▓▒▒░░       ░░▒▒▓▓████
 ███▓▓▒▒░    ░     ░▒▒▓▓███
████▓▓▒▒░░       ░░▒▒▓▓████
```

    Set by hand to show the fence and the shading — your own art comes out of the converter.

[ tips ]

Presets that work well in GitHub

compact logo

blocks, 60–80 columns, green or gray. Best for wordmarks and simple icons.

try compact

classic ramp

standard, 80–100 columns. Safer when the host font is unknown monospace.

try classic
[ quick_answers ]

When the banner does not survive the render

why did the ASCII banner collapse into a paragraph?

The art is outside the fence, or the fence opened with fewer than three backticks. Markdown treats runs of spaces as one space in normal prose, and those spaces are what carry the light tones. Nothing else about the art matters if the fence is wrong.

why does the banner scroll sideways on a phone?

Column count is too high. A fenced block does not wrap; it scrolls. Around 60 columns fits most phone-width README views, and the tool caps at 240 for the same reason it starts at 40 — beyond a certain width the art stops being readable in place.

why do the block characters look uneven in some renderers?

A renderer whose monospace stack has no glyph for ░▒▓█ substitutes a fallback face for just those characters, and the mark loses its even cell width. standard is plain 7-bit ASCII and cannot hit this, which is why it is the safer choice when you do not control the destination.

why does the ASCII banner look stretched?

Monospace cells are about three parts wide to five parts tall, and the converter emits rows on that assumption. A destination whose line height differs will squash or stretch the result — the characters are right, the grid is not. See the control reference.

[ convert ]

Make the banner now

Open the converter, drop a mark, copy the text. Your image never leaves the browser. Same logo headed for a login screen instead? The SSH MOTD guide covers the terminal-width version.

Convert image to ASCII privacy