How to Add an ASCII Banner to a GitHub README

A project name set as an ASCII banner makes the top of a README stand out. Unlike an image, it is plain text. It adds no file to the repository, and it looks right in both light and dark themes.

Adding it to a README

In Markdown, the banner has to go inside a code block. Outside one, repeated spaces collapse into a single space, and _ and * turn into italic and bold markers, which ruins the art.

```text
                                       _           _
 _ __ ___  _   _       _ __  _ __ ___ (_) ___  ___| |_
| '_ ` _ \| | | |_____| '_ \| '__/ _ \| |/ _ \/ __| __|
| | | | | | |_| |_____| |_) | | | (_) | |  __/ (__| |_
|_| |_| |_|\__, |     | .__/|_|  \___// |\___|\___|\__|
           |___/      |_|           |__/
```

# my-project

A tiny CLI tool you can run straight from the terminal.

• Writing text after the opening backticks turns off syntax highlighting, so the characters stay one color.
• Add a real text heading (# my-project) below the banner. Search engines and screen readers cannot read the banner as the project name.
• If the art contains three backticks in a row, wrap it in four backticks instead.

Keep it under 80 columns

A code block on GitHub scrolls sideways when a line is too long. A banner that is cut off defeats the purpose, so stay under 80 columns, or around 50 if you want it to fit on a phone as well.

Where it is read	Suggested width
GitHub README on a desktop	up to 80 columns
GitHub mobile app, narrow screens	about 50 columns
Terminal output	up to 80 columns

For a long project name, choose a smaller font such as Small or Mini instead of Standard or Big, or split the name over two lines. The top right corner of each font card on lab.ascii shows the width of the result.

Adding it to a code comment

A banner at the top of a file, or at the start of a large section, makes it easier to find your place in a long file.

/*
 *  ___ ___ _  _ ___  ___ ___
 * | _ \ __| \| |   \| __| _ \
 * |   / _|| .` | |) | _||   /
 * |_|_\___|_|\_|___/|___|_|_\
 */
export function render() {}

• Start every line with the comment marker (*, //, or #).
• If the art contains */, the block comment ends there. Use // line comments for that art.
• If your team enforces a line length limit, such as 100 characters, make the banner fit inside it.

Printing it when a program starts

To print a banner when a CLI tool starts, the art has to be stored as a string. The problem is the backslash (\). In most languages a backslash starts an escape sequence, so pasting the art as-is drops characters or causes an error.

In JavaScript, String.raw keeps backslashes as they are.

const banner = String.raw`
 _  _ ___ _    _    ___
| || | __| |  | |  / _ \
| __ | _|| |__| |_| (_) |
|_||_|___|____|____\___/
`;
console.log(banner);

A backtick or ${ inside the art ends the template string. It is usually easier to switch to a different font for that art.

In Python, use a raw string by putting r in front of it.

BANNER = r"""
 _  _ ___ _    _    ___
| || | __| |  | |  / _ \
| __ | _|| |__| |_| (_) |
|_||_|___|____|____\___/
"""
print(BANNER)

A startup banner stays out of the way if you follow two rules.

• Do not print it when the output goes to another program, such as a pipe or a log file.
• Offer an option such as --quiet to turn it off.

Which font should I use?

Font	Character
Standard	The safe default. It suits any name
Slant	Slanted letters with a sense of speed
Small	A smaller Standard. Good for long names
ANSI Shadow	Heavy letters filled with block characters. The most eye-catching
Calvin S	Small three-row letters. Good for code comments

ANSI Shadow and Calvin S use line and block characters outside ASCII (█ ╗ ═). They display well on GitHub and in most terminals, but may break in very old environments. If the banner must work everywhere, choose a font that uses only ASCII characters, such as Standard, Slant, or Small.

Type your project name on lab.ascii to compare banners in 12 fonts and click a card to copy it.