Your GitHub README is your project's landing page. Most look like this:
# my-project
A tool that does stuff.
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:
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%" />
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:
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
})
});
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 '[email protected]\n git add header.png
git diff --staged --quiet || git commit -m 'Update header image && git push
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.