ASCII Magic
Open tool

Animated ASCII art for a GitHub README

Put an animated ASCII banner, scene or loader at the top of your GitHub README. Copy a GIF or SVG, no build step, works in GitHub's dark and light themes.

Loading the builder…

/WHY

A README is the front door of a repository, and the top of it is the only part most visitors read. Something that moves there tells people the project is cared for before they read a word.

GitHub removes scripts and most styling from READMEs, so the art has to arrive as a file: an animated GIF for any piece, an animated SVG for a name banner, or plain text in a code block. The builder below makes all three and writes the Markdown around them, including the dark and light versions GitHub picks between for each reader.

/EXAMPLES

Ready-made examples to copy

Each one is complete. Copy it as it is, or change the piece name to any piece in the library.

Centred hero with title and badges

The classic open source header. The GIF, a centred title, two badges and a one line description.

<p align="center">
  <img src="assets/starry-ridge.gif" alt="Starry Ridge, animated ASCII art" width="720">
</p>

<h1 align="center">my-project</h1>

<p align="center">
  <img src="https://img.shields.io/github/license/you/my-project" alt="License">
  <img src="https://img.shields.io/github/stars/you/my-project" alt="Stars">
</p>

<p align="center">A tiny tool that does one thing well.</p>

Follows the reader's theme

Two GIFs, one drawn on GitHub's dark background and one on white. The browser shows the right one, so there is never a black box on a white page.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/hero-dark.gif">
  <source media="(prefers-color-scheme: light)" srcset="assets/hero-light.gif">
  <img src="assets/hero-dark.gif" alt="Animated ASCII art" width="720">
</picture>

Name banner as an animated SVG

Big ASCII letters with a gradient and a type-in effect, made in the banner maker. A few kilobytes and sharp at any size.

<p align="center">
  <img src="assets/banner.svg" alt="my-project" width="100%">
</p>

Two pieces side by side

A table keeps them on one row on wide screens and stacks them on phones.

<table>
  <tr>
    <td><img src="assets/spinning-torus.gif" alt="Spinning torus" width="360"></td>
    <td><img src="assets/bar-chart-race.gif" alt="Bar chart race" width="360"></td>
  </tr>
</table>

Text only, no image at all

A still frame inside a code block. Nothing to commit, works on npm, PyPI, crates.io and in any terminal that reads Markdown.

```text
              ...,,,,,--
         ,...,,,----~~~~~~~~
       ..,,,--~~~::::;;;;;;;;;
     ,,,,--~~::::::;;==!===!====
    ,,--~~~:::;===!!*******!!!!!!
```

Collapsible demo section

Keep the README short and put a bigger animation behind a click.

<details>
  <summary>See it running</summary>
  <p align="center"><img src="assets/boot-sequence.gif" alt="Boot sequence" width="640"></p>
</details>

How to do it

  1. Pick a piece from the library, or make a name banner with the banner maker.
  2. On the piece page, press Download GIF. For a banner, press Download SVG.
  3. Commit the file to your repo, for example in an assets folder.
  4. Reference it from README.md with the snippet below. Use a picture element if you export a light and a dark version.

Open the banner maker

/GUIDE

GIF, SVG or text: which one to use

Use a GIF for any piece from the library. It is the only animated image GitHub plays everywhere, including the mobile app. Keep it under about 2 MB so it loads fast: 4 seconds at 720 pixels wide is usually 300 KB to 1.5 MB.

Use an SVG for a name or title banner. The banner maker writes the animation into the file with CSS, which GitHub allows, so it stays a few kilobytes and stays sharp on high density screens.

Use a text block when the README is also shown somewhere that will not load images, like a package registry, a terminal Markdown viewer or a man page.

Making it look right in dark and light mode

About two thirds of GitHub readers use the dark theme. A GIF with a dark background looks like a black rectangle on the light theme, and the reverse looks like a white flash at night.

Export both versions with the two GIF buttons in the builder and wrap them in a picture element. GitHub passes the reader's theme to prefers-color-scheme, so each reader sees the one drawn for their background.

Sizing

GitHub's README column is about 830 pixels wide on desktop. Set the width attribute between 600 and 760 for a hero, or use width="100%" for a banner. On phones the image scales down by itself.

Do not set a height. The image keeps its own proportions.

Where to keep the file

Commit it to the repo, in a folder such as assets or .github. Relative paths like assets/hero.gif work on GitHub, but package registries need the full raw URL: https://raw.githubusercontent.com/owner/repo/main/assets/hero.gif. The npm tab in the builder writes that for you.

Avoid hotlinking images from other sites. They can disappear, and GitHub caches them through its own proxy anyway.

Accessibility

Always write alt text that says what the picture is, for example "Starry Ridge, animated ASCII art". Screen readers read it, and it shows if the image fails to load.

GitHub does not pause GIFs for readers who prefer reduced motion. If your audience includes people who are sensitive to motion, choose a calm piece, or use the PNG or text version instead.

Pieces that work well for this

Open any of them to copy the code or export.

Amsterdam Canal BicyclesCities of the World
Analog Wall ClockThings
Apollonian GasketAlgorithms
Asteroid BeltCosmos
Aurora CurtainsDemoscene
Autumn Road CyclistLandscapes
Bar Chart RaceLive Data
Home Computer BASICRetro Computing

/FAQS

Animated ASCII art for a GitHub README: frequently asked questions

Q. How do I add animated ASCII art to my GitHub profile README?
Export a GIF from any piece, commit it to your profile repository, and reference it with an img tag at the top of README.md. The builder on this page writes that Markdown for you, with your project name, a tagline and optional badges, and it makes dark and light GIFs so the art matches each reader's GitHub theme.
Q. What is a GitHub profile README?
A GitHub profile README is the README.md in a repository named exactly like your username, and GitHub shows it at the top of your profile page. It is Markdown with some HTML allowed, so animated art has to arrive as an image: a GIF for any library piece, or an animated SVG banner from the banner maker at README banner maker.
Q. How do I put ASCII art in a README so it keeps its shape?
Paste it inside a fenced code block that opens with three backticks and the word text. Code blocks use a monospace font, so every character lines up. The builder's Text block tab writes a still frame this way, which needs no image file and also shows on package registries and in terminal Markdown viewers.
Q. Why doesn't the ascii-art script tag work in my GitHub README?
GitHub removes every script from Markdown for security, so the embed tag cannot run in a README. Use the GIF, the animated SVG banner or the text block instead. Keep the script tag for real web pages, such as a GitHub Pages site, where it plays the piece live.
Q. Should I use a GIF, an SVG or text for GitHub README ASCII art?
Use a GIF for any library piece, an SVG for a name banner, and text when the README is also shown where images do not load. GIFs play everywhere on GitHub, including the mobile app. SVG banners from the banner maker are a few kilobytes and stay sharp on high density screens.
Q. How do I make README art match GitHub's dark and light themes?
Download both the dark and the light GIF from the builder and copy the Dark + light tab, which wraps them in a picture element. GitHub passes each reader's theme to prefers-color-scheme, so dark theme readers see the GIF drawn on GitHub's dark background and light theme readers see the white one.
Q. How wide should a GIF be in a GitHub README?
Between 600 and 760 pixels suits a hero, because the README column is about 830 pixels wide on desktop. Set the width slider in the builder to match, since it controls both the GIF export and the width attribute in the Markdown. Do not set a height; the image keeps its proportions and scales down on phones.
Q. How do I keep a README GIF small enough to load quickly?
Keep it under about 2 MB by keeping it short and no wider than it is shown. The builder exports 4 seconds at the width you choose, which is usually 300 KB to 1.5 MB at 720 pixels. Calm pieces with large flat areas compress better than busy ones such as Digital Rain.
Q. Why is my README image broken on npm or PyPI?
Package registries cannot load images from relative paths like assets/hero.gif. Point the img tag at the raw file on GitHub instead, using raw.githubusercontent.com with your owner, repository, branch and path. The npm / PyPI README tab in the builder writes that full URL from the repo name you enter.
Q. How do I make an animated name banner for the top of a README?
Use the README banner maker at README banner maker. Type your project name, pick a font, a color gradient and an animation such as Type in or Shimmer, then download the SVG and commit it. The animation lives inside the file, so it plays in a GitHub README without any scripts.
Q. Is animated ASCII art in a README accessible?
It can be, as long as you write alt text and choose a calm piece. The builder fills the alt text with the piece name, for example Spinning Torus, animated ASCII art. GitHub does not pause GIFs for readers who prefer reduced motion, so for sensitive audiences use the PNG or the text block instead.
Q. Can I use the library's ASCII art in a company or commercial repository?
Yes. Every piece in the library is MIT licensed, so you can use it in personal, open source and commercial repositories. A credit or link back to ascii-magic.com is appreciated but not required. The same applies to the GIFs, PNGs and text frames you export from the piece pages.

Other ways to use it

Each one has its own builder.

Website

An animated ASCII hero for GitHub Pages

Add a live, animated ASCII art hero to a GitHub Pages or personal website with one script tag. No framework, no build step, under 10 KB per piece.

Terminal

A terminal welcome screen with animated ASCII art

Show an animated ASCII piece every time you open a terminal, or set a still one as your server's message of the day. Works with zsh, bash and fish.

CLI

Splash screens and loaders for command line tools

Give your CLI a startup splash or an animated loader in ASCII. Copy the piece source into your Node project, or print frames from any language.

Loader

ASCII loading spinners and progress bars for websites

Lightweight animated ASCII loaders, spinners and progress bars for web pages. One tag to embed, no images to download, honours reduced motion.

Error page

Animated ASCII art for 404 and error pages

Make a 404 or 500 page people remember with animated ASCII art. Ready-made error pieces plus any scene or creature, embedded with one tag.

Wallpaper

ASCII art wallpapers for desktop and phone

Download ASCII art wallpapers in 4K, 1080p and phone sizes. Pick any scene, choose dark or light, and export a full-resolution PNG in one click.