/ README
Getting the banner is the easy part. Making it survive GitHub's markdown renderer is where most people lose an afternoon.
This is the whole trick. Outside a fenced block GitHub renders README text in a proportional font and collapses runs of spaces — both of which destroy character alignment. Inside one, the spacing is preserved exactly.
```
_ _
_ __ ___ _ _ _ __ _ __ ___ (_) ___ ___| |_
| '_ ` _ \| | | |_____| '_ \| '__/ _ \| |/ _ \/ __| __|
| | | | | | |_| |_____| |_) | | | (_) | | __/ (__| |_
|_| |_| |_|\__, | | .__/|_| \___// |\___|\___|\__|
|___/ |_| |__/
```That is what you paste into README.md, backticks included.
GitHub's README column is a fixed width. A banner wider than roughly 80 characters gets a horizontal scrollbar, which reads as broken on desktop and is genuinely unusable on a phone. Short project names in a large font, or longer names in a compact font — not both.
If your name is long, a smaller FIGlet font like small or mini will fit where big or block will not.
It is tempting to screenshot the banner and commit it as an image. Do not. GitHub serves both a light and a dark theme, and a PNG with a dark background renders as a black rectangle for everyone on the light theme — and the reverse for the other half of your visitors.
Text inside a code fence inherits whatever colour the reader's theme uses, so it is correct in both. It also stays searchable, diffable, and readable in a terminal via cat README.md.
If your generator or editor emitted tabs, GitHub will expand them to a different width than your editor did, and the art will shear. Run the text through a tab-to-space conversion before committing. Most ASCII generators emit spaces only, but text copied out of a terminal sometimes does not.
Converting an actual image gives you a picture rather than a word. The same code-fence rule applies, and the same width limit — a picture needs more columns than a word to stay legible, so this works best for simple, high-contrast shapes.
The same text works as a startup banner for a CLI. Embed it as a string in your source, or print it from a file at launch.
Large ASCII headings inside a long source file make sections findable when scrolling fast. Keep these narrower than your editor's wrap column.
The text to ASCII art generator turns a project name into banner lettering with 17 FIGlet fonts, and has a "Copy for Discord" button that wraps the output in a code fence — the same fence a README needs. For a logo or screenshot, the image to ASCII converter handles pictures. Both run in your browser with nothing uploaded.
Put it inside a fenced code block — three backticks above and below. Outside a code block GitHub renders the README in a proportional font and collapses runs of spaces, which destroys the alignment.
Almost always the code fence. A second cause is tabs: GitHub expands them differently from your editor, so convert any tabs to spaces before pasting.
Keep it under about 80 characters. GitHub's README column is fixed width and anything wider gets a horizontal scrollbar, which looks broken on mobile.
Plain ASCII inside a code block does, because it inherits the theme's text colour. An ASCII banner saved as a PNG will not — a dark-background image looks like a black rectangle on a light theme. Use text if you care about both themes.
Issues and pull request comments support code fences, so yes. The short repository description field is single-line plain text, so no.