ASCII Magic
Open tool

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.

Loading the builder…

/WHY

GitHub Pages serves plain files, which is exactly what an ASCII hero needs. There is no build step and no framework: one script tag adds an ascii-art element to the page, and that element plays the piece.

The builder below writes a complete index.html with your name, headline, button and colours, in one of three layouts. Download it, push it to a repository called yourname.github.io, and your site is live with a moving hero.

/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.

The smallest working page

Ten lines. Save as index.html, push to yourname.github.io, done.

<!DOCTYPE html>
<html lang="en">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Ada Example</title></head>
<body style="margin:0;min-height:100vh;display:grid;place-items:center;background:#000;color:#eee;font-family:system-ui">
  <main style="text-align:center">
    <ascii-art piece="starry-ridge" size="5"></ascii-art>
    <h1>Ada Example</h1>
  </main>
  <script type="module" src="https://www.ascii-magic.com/ascii/ascii.js"></script>
</body>
</html>

Art as a full-screen background

The piece fills the page behind your text, dimmed so the words stay readable.

<section style="position:relative;min-height:100vh;display:grid;place-items:center;overflow:hidden;background:#05060a;color:#fff">
  <div style="position:absolute;inset:0;display:grid;place-items:center;opacity:.4;pointer-events:none">
    <ascii-art piece="ocean-sunset" look="dots" size="6"></ascii-art>
  </div>
  <h1 style="position:relative;font:700 56px system-ui">Hello, I'm Ada.</h1>
</section>
<script type="module" src="https://www.ascii-magic.com/ascii/ascii.js"></script>

Jekyll layout include

For Pages sites built with Jekyll. Save the first block as _includes/ascii-hero.html and add the second line to any layout.

<!-- _includes/ascii-hero.html -->
<div class="ascii-hero" style="display:flex;justify-content:center;padding:32px 0">
  <ascii-art piece="{{ include.piece | default: 'moonlit-sea' }}" size="{{ include.size | default: 9 }}"></ascii-art>
</div>
<script type="module" src="https://www.ascii-magic.com/ascii/ascii.js"></script>

<!-- in a layout or page -->
{% include ascii-hero.html piece="spinning-torus" size=10 %}

Hugo shortcode

Save as layouts/shortcodes/ascii.html, then write {{< ascii piece="moonlit-sea" >}} in any Markdown file.

<!-- layouts/shortcodes/ascii.html -->
<ascii-art piece="{{ .Get "piece" | default "moonlit-sea" }}" size="{{ .Get "size" | default "10" }}"></ascii-art>
{{ if not (.Page.Scratch.Get "asciiLoaded") }}{{ .Page.Scratch.Set "asciiLoaded" true }}
<script type="module" src="https://www.ascii-magic.com/ascii/ascii.js"></script>
{{ end }}

Halftone look with custom dots

Any piece can be drawn as dots. Make them smaller and use five sizes for a finer screen.

<ascii-art piece="starry-ridge" look="dots" dot-size="60" steps="5" size="5"></ascii-art>
<script type="module" src="https://www.ascii-magic.com/ascii/ascii.js"></script>

How to do it

  1. Choose a piece. Scenes and 3D shapes make strong heroes.
  2. Paste the script tag once, near the end of your page.
  3. Place the ascii-art element where the hero should sit, and set its size.
  4. Push to your Pages branch. The piece plays as soon as the page loads.

/GUIDE

How the tag behaves on a live site

The ascii-art element loads only the piece it needs, usually 3 to 40 KB. It plays only while it is on screen and stops when the tab is hidden, so it costs nothing when nobody is looking.

Visitors who turn on reduced motion in their system settings see one still frame instead of an animation. You do not have to do anything for that.

Sizing the art

Text pieces are sized by font size: the size attribute is the font size in pixels, and the piece is its number of columns wide. A 96 column piece at size 8 is about 460 pixels wide.

For a hero, aim for 40 to 60 percent of the viewport width on desktop. On phones, the element never grows wider than its container; if it is wider than the screen, lower the size or wrap it in a box with overflow hidden as the full page does.

Custom domains and HTTPS

If you point your own domain at GitHub Pages, keep "Enforce HTTPS" on. The script is served over HTTPS and browsers block it from an insecure page.

Speed

The script is a module, so it never blocks your page from showing. For the fastest first paint, put the script tag at the end of body as in the full page example, and keep the hero text in plain HTML so search engines and readers see it immediately.

Pieces that work well for this

Open any of them to copy the code or export.

Arctic IcebergsLandscapes
Aurora Cabin SnowfallLandscapes
Autumn ForestLandscapes
Autumn Pagoda MaplesLandscapes
Autumn Road CyclistLandscapes
Balloon Valley SunriseLandscapes
Camel Caravan DuskLandscapes
Campfire Under StarsLandscapes

/FAQS

An animated ASCII hero for GitHub Pages: frequently asked questions

Q. How do I add an ASCII art hero to a GitHub Pages website?
Paste one script tag near the end of your page and an ascii-art element where the hero should sit, then push to your Pages repository. The element loads the piece, plays it while it is on screen and holds a still frame for visitors who prefer reduced motion. No build step or framework is needed.
Q. Where can I get animated ASCII art for a website?
Right here: every piece in the library, about 634 of them, can go on a website with one script tag and one ascii-art element that names the piece, such as moonlit-sea. It works on any plain HTML page, including GitHub Pages. Attributes set the size, speed, look and background.
Q. Can the builder make a whole ASCII art website for me?
Yes, it writes a complete single-file index.html with your name, a headline, a button and your colors around the animated piece. Choose one of three layouts: text left and art right, art above the text, or art behind the text. Download the file, push it, and your ASCII art website is live.
Q. Do I need npm or a build step to use ASCII art on GitHub Pages?
No. GitHub Pages serves your HTML file as it is, and the script loads from ascii-magic.com, so a repository with one index.html is enough. The builder also offers a deploy workflow file, but you only need it if your repository already has a build step.
Q. How do I publish the page at yourname.github.io?
Create a repository named exactly yourname.github.io, add the index.html from the builder at the root or in a docs folder, and push. GitHub Pages publishes it within a minute or two. For a custom domain, add it in the repository's Pages settings and keep Enforce HTTPS on, because the script is served over HTTPS.
Q. How do I add the ASCII hero to a Jekyll site?
Save the builder's Jekyll include as _includesASCII library-hero.html, then write {% include ascii-hero.html %} in any layout or page. The include holds the ascii-art element and the script, so the hero appears wherever you place that line. Jekyll sites on GitHub Pages rebuild it automatically when you push.
Q. How do I size ASCII art so it fits on phones?
Set the size attribute, which is the font size in pixels: a piece 96 columns wide at size 8 is about 460 pixels across. The element never grows wider than its container, and the builder's layouts wrap the art in a box with overflow hidden, so a wide piece crops neatly on small screens instead of scrolling sideways.
Q. Will an animated ASCII hero hurt my Lighthouse score?
Very little. The script is a small module that loads after your content, only the visible piece is fetched, and it draws only while on screen. Keep your headline as real HTML text rather than inside the art, so the text can be the largest contentful paint and search engines read it straight away.
Q. Can I host the ASCII art files on my own site instead of ascii-magic.com?
Yes. The library is MIT licensed, so you can copy ascii.js, the runtime files it imports, kit.js and the pieces you use into your repository. Keep the same folder layout so the player finds each piece, then point the script tag at your copy. Self-hosting also lets the page work without reaching our server.
Q. Can I change the colors of an ASCII piece on my website?
Yes, within limits. Colored pieces keep their own palette, but adding the mono attribute draws the piece in one color taken from the element's CSS color. The bg attribute sets the background, and the look attribute redraws any piece as halftone dots, ASCII, binary, blocks or your own characters.
Q. What do visitors who prefer reduced motion see?
They see a single still frame instead of the animation, with nothing extra for you to set up. The player checks the prefers-reduced-motion setting before it starts. Screen readers get a label with the piece name, such as Moonlit Sea, animated ASCII art, and you can set your own aria-label on the element.
Q. Can I make a social preview image for my site from the same piece?
Yes. The builder's Social preview PNG button exports the piece at 1280 by 640 pixels in your background and text colors, the size GitHub recommends for repository previews. Use it as your page's og:image, or upload it in your repository settings as the social preview.

Other ways to use it

Each one has its own builder.

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.

YouTube

ASCII art for YouTube thumbnails

Export any animated ASCII piece as a 1280 by 720 YouTube thumbnail background, then add your title on top in any editor.