Adding an animated command-line prompt to your project or profile README is one of the quickest ways to show what your tool does. It gives visitors immediate context, mimicking how a developer interacts with your CLI or package in real time.

Many developers try to achieve this using dynamic SVGs hosted on external servers or automated workflows via GitHub Actions. While those can work, they often come with friction: setting up workflow YAML files, waiting for build minutes, dealing with aggressive CDN caching when you push an update, or handling broken SVG embeds when external endpoints experience downtime.

A lightweight, browser-rendered GIF sidesteps all of that complexity. Here is a practical walkthrough on how to generate and embed a clean, terminal-style typing GIF directly into your markdown—no workflows or external services required.

Step 1: Generate a Clean Terminal GIF

To keep your workflow lean, you can use a browser-based tool like typinggif. There is no sign-up or watermark, and all rendering and encoding happen entirely inside your browser on your device—your text is never sent to a remote server.

  1. Select the Style: Choose the Terminal style. This automatically formats the animation with a command prompt ($), monospace typography, and a block cursor.
  2. Choose a Developer Font: Pick a clean monospace font such as JetBrains Mono, IBM Plex Mono, or Space Grotesk.
  3. Draft Your Command: Keep your copy under the 280-character limit. Focus on the core command and a short output message. You can also rotate the ending if you want to cycle through multiple commands.
  4. Choose Aspect Ratio & Colors: A Banner or 16:9 ratio generally looks best centered in a README. Choose a color palette that matches your documentation theme.
  5. Export: Export as a GIF. The free tier gives you exports up to 800 px on the longest edge at 15 fps (up to 10 seconds), with no export limits or watermarks. Optional paid credits are available if you need 1080p and up to 60 seconds.

If you want a step-by-step visual overview, see how to add a typing animation to your GitHub README.

Step 2: Add the GIF to Your Repository

Rather than linking to third-party file hosts that might break later, commit the asset directly to your repository:

  1. Create a directory like .github/assets/ or docs/images/ in your repository.
  2. Add your exported GIF (e.g., terminal-demo.gif).
  3. Commit and push the file.

Step 3: Embed It in Markdown

The simplest way to display your animation is with standard markdown:

![Terminal Demo](.github/assets/terminal-demo.gif)

If you prefer to center it or constrain the display width on large screens, use standard HTML:

<p align="center"> <img src=".github/assets/terminal-demo.gif" alt="Terminal Demo" width="600" /> </p>

Pro-Tip: Support Dark and Light Mode

GitHub allows dynamic image switching based on the user's system theme via the <picture> tag. If you export two variations—one with a dark background and one with a light background—you can display the correct one automatically:

<picture> <source media="(prefers-color-scheme: dark)" srcset=".github/assets/terminal-dark.gif"> <source media="(prefers-color-scheme: light)" srcset=".github/assets/terminal-light.gif"> <img alt="Terminal Demo" src=".github/assets/terminal-dark.gif" width="600" /> </picture>

GitHub's markdown renderer evaluates prefers-color-scheme, ensuring your terminal preview looks native regardless of the reader's settings.

File Size and Performance Advice

When using GIFs in documentation, keeping file sizes low is critical for fast page loads, especially on mobile networks:

  • Stick to 800 px: You rarely need higher than 800 px width for a GitHub README column. Full-width images on GitHub display around 800 px wide anyway, so larger assets waste bandwidth without visible sharpness gains.
  • Limit Duration: Keep your animation concise. Free GIF exports support up to 10 seconds, which is plenty of time for a single command and output.
  • Keep Text Concise: GIFs compress repeated patterns efficiently. Monospace text against a solid background compresses down significantly better than complex gradients or full-motion screen recordings.

By keeping the asset static, versioned in git, and rendered on the client, your README stays fast, reliable, and completely maintenance-free.

— typinggif team (we build this tool)

Note: typinggif is an independent tool, unofficial and not affiliated with or endorsed by GitHub or other brands mentioned.