ASCII Magic
Open tool

ASCII art for docs sites and landing pages

Add animated ASCII art to docs and landing pages built with Next.js, Astro, Docusaurus or plain HTML. Diagrams, terminals and heroes that load instantly.

Loading the builder…

/WHY

Documentation is mostly text, which is exactly why one moving picture at the top of a page, or a small animated diagram beside a hard idea, makes it easier to read and easier to remember.

The builder writes the component and the page for Docusaurus, VitePress, Astro Starlight, Next.js and Nextra, Mintlify, MkDocs and plain HTML, as a page hero or as a captioned figure. Every version loads the art only in the browser, so static builds and server rendering keep working.

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

Animated diagram as a figure

Diagram pieces such as Flowchart, Sequence Diagram and CI Pipeline explain a process while they move.

<figure style="display:flex;flex-direction:column;align-items:center">
  <ascii-art piece="sequence-diagram" size="8"></ascii-art>
  <figcaption>How a login request moves between services</figcaption>
</figure>
<script type="module" src="https://www.ascii-magic.com/ascii/ascii.js"></script>

Landing page hero beside the headline

A two column hero for a product or open source landing page.

<section style="display:grid;grid-template-columns:1fr 1fr;gap:48px;align-items:center;padding:96px 6vw">
  <div>
    <h1>Ship faster with Acme SDK</h1>
    <p>Typed, tiny and fast. Works anywhere JavaScript runs.</p>
    <a href="/docs">Read the docs</a>
  </div>
  <ascii-art piece="spinning-torus" size="10"></ascii-art>
</section>
<script type="module" src="https://www.ascii-magic.com/ascii/ascii.js"></script>

Docusaurus: one line in any MDX page

After adding the component from the builder, use it anywhere.

import Ascii from "@site/src/components/Ascii";

<Ascii piece="architecture-map" size="8" caption="The three services and how they talk" />

Dark and light themes

Text pieces use the page's text colour when you add mono, so they follow your docs theme automatically.

<!-- follows the theme's text colour -->
<ascii-art piece="flowchart" mono size="8" style="color: var(--ifm-font-color-base)"></ascii-art>

How to do it

  1. Pick a diagram, terminal or hero piece.
  2. In plain HTML or Astro, use the script tag. In React or Next.js, copy the piece source and render its frames in a pre element.
  3. Size it with the size attribute or your own CSS.

/GUIDE

Static builds and server rendering

Docs tools build pages ahead of time on a server, where there is no browser. The components from the builder only load the script in the browser (BrowserOnly in Docusaurus, ClientOnly in VitePress, an inline module script in Astro), so builds never fail on the custom element.

VitePress and other Vue based tools must be told that ascii-art is a custom element; the builder includes that config line.

Use diagrams where they help

A static diagram shows the parts; an animated one shows the order. Use a moving diagram where the sequence matters, such as a request flow, a build pipeline or a state machine, and keep the explanation in the text beside it so it is searchable and accessible.

Keep pages fast

One script for the whole site, loaded once and cached, and one small file per piece. Pieces only play while on screen. For a page with many figures, that still means only the visible ones are drawing.

Pieces that work well for this

Open any of them to copy the code or export.

API Request InspectorUI
Architecture MapExplainers
Benchmark ResultsUI
Binary Search StepsExplainers
Binary Search TreeExplainers
Firmware Setup UtilityUI
Bisect HuntUI
Blue Green SwitchExplainers

/FAQS

ASCII art for docs sites and landing pages: frequently asked questions

Q. How do I add ASCII art to a docs site?
Pick your docs tool in the builder and copy the files it writes: a small component plus a page that uses it. Every version loads the script only in the browser, so static builds and server rendering keep working. Choose Page hero for the top of a page, or Figure in the text for a captioned diagram.
Q. Which docs tools does the builder write ASCII art for?
It writes files for Docusaurus, VitePress, Astro Starlight, Next.js with Nextra, Mintlify, MkDocs and plain HTML. Each tab gives exact file paths, such as src/components/Ascii.jsx for Docusaurus or the lines to add to mkdocs.yml for MkDocs, so you can paste them straight into your repository.
Q. Why does my docs build fail with customElements is not defined?
The script ran during the server build, where there is no browser. Use the component from the builder, which loads it only in the browser: BrowserOnly in Docusaurus, ClientOnly in VitePress, an inline module script in Astro and a client component in Next.js. Or wrap your own code in your tool's client-only wrapper.
Q. How do I add an animated ASCII diagram to documentation?
Choose a diagram piece such as Flowchart, Sequence Diagram, CI Pipeline or Architecture Map, set Where to Figure in the text, and write a caption. The builder wraps the piece in a figure with a figcaption. Use a moving diagram where order matters, like a request flow, and explain it in the text too.
Q. How do I add ASCII art to MkDocs?
Add the script to extra_javascript as a module in mkdocs.yml and turn on the md_in_html extension, as the MkDocs tab shows. Then place the ascii-art element inside a div with the markdown attribute in any page. Choose Figure in the text and the builder adds your caption under it.
Q. Why won't Mintlify run my script tag?
Mintlify limits custom scripts, so the Mintlify tab uses an iframe of the embed page instead. Save the snippet as snippetsASCII library.mdx and import it into any page. It shows the same piece on a transparent background and needs no script on your side.
Q. How do I make VitePress accept the ascii-art element?
Tell Vue that ascii-art is a custom element by adding isCustomElement to the template compiler options in .vitepress/config.js, as the builder's third file shows. The theme file registers an Ascii component and loads the script only in the browser, so builds do not fail.
Q. How do I make ASCII art follow my docs' dark and light theme?
Add the mono attribute so the piece is drawn in one color, then set that color from your theme's text color variable in CSS. When readers switch themes, the art switches with the text. Without mono, colored pieces keep their own palette on both themes.
Q. How do I add an ASCII hero to a product landing page?
Place the ascii-art element next to your headline in a two-column section and add the script once at the end of the page. Rotating shapes such as Spinning Torus, Tesseract or Wireframe Globe suit a product hero. Keep the headline as real text so it stays the page's main content for readers and search engines.
Q. Will animated figures slow down my documentation?
Not noticeably. The site loads one script, cached after the first page, and one small file per piece. Pieces only draw while they are on screen, so a long page with many figures only animates the ones the reader can see. Text and code still load first.
Q. Can screen readers understand an ASCII diagram?
Not from the art alone. The element is labeled with the piece name, such as Sequence Diagram, animated ASCII art, and the drawing itself is hidden from screen readers. Always explain the diagram in the text or the caption, which the builder adds as a figcaption when you choose Figure in the text.
Q. Can I use the same ASCII art in a PDF or a slide deck?
Yes, as an image. The builder's Download GIF button exports 4 seconds of the piece at 960 pixels wide for places that cannot run scripts. Slide apps play the GIF, but most PDF viewers show only its first frame, so for a PDF, pause the piece on its own page and export a PNG still instead.

Other ways to use it

Each one has its own builder.

Chat

ASCII art you can paste into Discord and Slack

Copy any ASCII piece as plain text and paste it into Discord, Slack or Teams inside a code block, so it keeps its shape.

Code

ASCII art headers for source code comments

Copy ASCII art and block-letter banners as text for file headers and section comments in your code.

OBS

Animated ASCII overlays for OBS and streams

Use animated ASCII art as a browser source in OBS or Streamlabs for starting soon screens, borders and overlays.

Slides

ASCII art for slides and presentations

Drop animated ASCII art into Keynote, PowerPoint or Google Slides as a GIF or video, for title slides and section breaks.

Portfolio

ASCII art for a developer portfolio

Make a developer portfolio stand out with an animated ASCII hero, a terminal-style about section and live ASCII charts.

Dashboard

ASCII charts for status pages and dashboards

Animated ASCII bar charts, gauges, sparklines and uptime bars for status pages, internal dashboards and terminal tools.