DEV Community

Mack
Mack

Posted on

How to Make Your GitHub README Stand Out with Dynamic Images

#github #webdev #tutorial #opensource

Your GitHub README is your project's landing page. Most look like this:

# my-project
A tool that does stuff.
Enter fullscreen mode Exit fullscreen mode

Here's how to make yours actually catch people's attention.

1. The Social Preview Problem

When someone shares your repo on Twitter, Slack, or Discord, GitHub generates a generic preview card. It shows your repo name, description, and... that's it.

You can set a custom social preview in Settings → Social Preview, but:

  • You need to design it manually
  • It's static (doesn't update with your repo stats)
  • Most people never bother

2. Dynamic Badges (The Easy Win)

You probably already know about shields.io:

![GitHub stars](https://img.shields.io/github/stars/your/repo)
![License](https://img.shields.io/github/license/your/repo)
![Build](https://img.shields.io/github/actions/workflow/status/your/repo/ci.yml)
Enter fullscreen mode Exit fullscreen mode

These update automatically. But they're tiny — good for metadata, not for visual impact.

3. Generated Header Images

Here's where it gets interesting. You can generate a custom header image using an API:

<img src="https://your-image-api.com/render?title=My%20Project&subtitle=A%20fast%20CLI%20tool&theme=dark" width="100%" />
Enter fullscreen mode Exit fullscreen mode

This gives you a full-width, designed header that:

  • Matches your project's brand
  • Can include dynamic data (version, stars, etc.)
  • Looks professional without Figma

4. Screenshot Your App Automatically

If your project has a web UI, you can embed a live screenshot:

![App Screenshot](https://your-screenshot-api.com/capture?url=https://your-app.com&width=1200&height=630)
Enter fullscreen mode Exit fullscreen mode

This is especially powerful for:

  • Design tools — show the actual UI
  • Dashboards — show real (demo) data
  • Documentation sites — show the docs look polished

5. HTML-to-Image for Custom Cards

The most flexible approach: write HTML/CSS, render it as an image.

const response = await fetch('https://your-api.com/html-to-image, {
  method: 'POST,
  headers: { 'Content-Type: 'application/json },
  body: JSON.stringify({
    html: '<div style="padding:40px;background:#1a1a2e;color:white;font-family:sans-serif"><h1>My Project</h1><p>v2.1.0 • 1.2k stars • MIT</p></div>,
    width: 1200,
    height: 630
  })
});
Enter fullscreen mode Exit fullscreen mode

You get pixel-perfect control with familiar web tech.

6. Automate It with GitHub Actions

The real power move: regenerate your README images on every push.

name: Update README Images
on:
  push:
    branches: [main]

jobs:
  update-images:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate header
        run: |
          curl -o header.png 'https://your-api.com/render?title=My+Project&stars='$(curl -s https://api.github.com/repos/${{ github.repository }} | jq .stargazers_count)
      - name: Commit if changed
        run: |
          git config user.name 'github-actions\n          git config user.email 'actions@github.com\n          git add header.png
          git diff --staged --quiet || git commit -m 'Update header image && git push
Enter fullscreen mode Exit fullscreen mode

Now your README always reflects the latest stats.

7. Tools That Help

Here are some options for generating these images:

  • Rendly — Screenshot and HTML-to-image API with built-in templates (disclaimer: I built this)
  • GitHub's built-in social preview — Manual upload, static
  • Capsule Render — SVG-based headers for READMEs
  • Socialify — Generates GitHub social images

The Takeaway

A good README with visual elements gets more stars, more contributors, and more users. It takes 10 minutes to set up and runs forever.

Don't let your best project look like every other repo on GitHub.

What does your README look like? Drop a link in the comments — I'll give feedback.

Top comments (0)