URL-based repository banners. Think shields.io, but for headers. ✨
I believe every repository deserves to look beautiful. Your code is art, your projects deserve stunning visuals to match. But design tools steal hours you don't have. So I built a service that generates gorgeous banners through simple URL parameters. Instant, customizable, and no design tools required. Because great projects deserve great repository banners.
Create a banner · Documentation · Public pages · Banner rendering · API reference · Self-hosting · Brand guidelines · Agent skill · Terms · Privacy
When you deploy your own copy, you're directly supporting this project! 💖
- 🎨 Backgrounds — Solid colors, gradients, transparency, presets, and public HTTPS images.
- 📸 Image search and styling — Pexels search with more results, image blur, and background color filters.
- 🔤 Typography — Google Fonts, emoji, Simple Icons using
![slug], and inline custom images using![icon src="https://…"]. - 🧩 Custom Images — Position multiple logos or decorations, resize and rotate them, preserve proportions, and arrange them behind or in front of text.
- 📥 Output — Live preview, README Markdown, image URLs, SVG, and PNG downloads.
- 💖 Optional attribution — Toggle the watermark and choose any corner.
- 📚 Accessible controls — Keyboard-selectable photos and responsive Code of conduct and MIT license tabs.
- 📖 Project pages — Documentation at
/docsand optional usage stats in the generator sidebar. - 🔒 Simple usage stats — Optional daily counts of successful banner renders; designs are not saved.
- 🐳 Self-hosting — Docker Compose with required Redis for persistent search caching and quota control.
- 🤖 Agent skill — Create banner URLs and README Markdown from compatible AI coding tools.
- Open ghrb.waren.build.
- Set your text, fonts, and background; optionally add custom images and check the live preview.
- Copy Markdown or an image URL, or download SVG/PNG. Exports run in your browser; designs are not saved on the server.
You can also create a banner directly with a URL:
Use Docker Compose to run the app and its required Redis database:
git clone https://github.com/warengonzaga/github-repo-banner.git
cd github-repo-banner
cp .env.example .env
docker compose up --build -dOpen http://localhost:3000. See the self-hosting guide for configuration, Railway deployment, and development commands.
Use color, gradient, image, and styling parameters to control the banner background.
https://ghrb.waren.build/render/banner?header=My+Project&bgimg=https://images.pexels.com/photos/1261728/pexels-photo-1261728.jpeg&bgblur=10&bgbrightness=60&bggrayscale=100&color=ffffff
See background effects and parameters.
Add inline icons or freely positioned images from the generator:
![icon src="https://example.com/logo.png" w="100%"] My Project
Use public HTTPS image URLs. See the custom image settings for limits, positioning, rotation, and validation rules.
Hosted and self-hosted instances can offer Pexels search when PEXELS_API_KEY is configured. Direct image URLs work without a key; see self-hosting configuration.
The UI enables attribution by default. Use the output controls or support=true to control generated banner links; see the Banner Rendering guide.
The generator includes the repository README, Code of Conduct, and MIT license. Open the Documentation page when you need the full guides. Usage stats appear in the generator sidebar when enabled.
See the public pages guide for browser-facing routes and the Banner Rendering guide for generated SVG URLs. The API reference covers /api/health and /api/pexels/search.
Projects and organizations using GitHub Repo Banner:
- gogcli by steipete - Google in your terminal
- BetterGov PH - Making government services better for Filipinos
The standalone github-repo-banner skill creates banner URLs and README Markdown using this service, with project branding and explicit preview checks. It needs no other Clean plugin or API key.
With a Codex version supporting plugins, install from the repository's marketplace:
codex plugin marketplace add warengonzaga/github-repo-banner
codex plugin add github-repo-banner@github-repo-bannerStart a fresh session after installation. For a local checkout, use codex plugin marketplace add /absolute/path/to/github-repo-banner.
Example requests:
$github-repo-banner create a banner for this project's README using its existing colors, preview it, and give me the Markdown without editing files
$github-repo-banner use a transparent background and a GitHub icon, then replace the existing README banner
$github-repo-banner create a banner using my self-hosted base URL https://banners.example.com
Other Agent Skills-compatible hosts can load skills/github-repo-banner directly. Copy the whole folder, including references/, into the host's documented skill directory; no plugin manifest is required for this mode. In Codex, a project-local direct installation can use .agents/skills/github-repo-banner/. Do not install both forms in the same project/session if that would expose duplicate skills.
The skill distinguishes generated URLs from verified renders and edits a README only when requested. /render/banner returns SVG; PNG export remains a browser-side UI feature. Maintain the skill reference alongside the route, sanitizer, renderer, and generator's Markdown behavior. Run bun scripts/check-banner-skill.ts to check the documented URL example against the route, encoding, limits, fallback, and package linkage.
Usage tracking is optional, and exported designs are not saved. Read the Privacy Policy and Terms of Service for the complete details.
Node.js · TypeScript · Hono · tsup · Bun
bun run check # Static checks
bun run build # Production build and declaration generationRegression checks are in scripts/check-* (run .ts files with Bun and .mjs files with Node). CI runs static checks, the build, regression scripts with disposable Redis, and the Docker smoke check. See the self-hosting guide.
Contributions are welcome! For major changes, open an issue first.
- Fork and clone the repository, then add the original repository as
upstream. - Create a feature branch from
upstream/dev(git fetch upstream dev && git switch -c feature/amazing-feature upstream/dev). - Commit with Clean Commit convention.
- Push your branch and open a Pull Request targeting
dev.
MIT License - see LICENSE file.
Waren Gonzaga • GitHub • Website
If GitHub Repo Banner has been useful, you can support my open-source work by sponsoring me on GitHub or, if you think my work deserves wider recognition, nominating me for the GitHub Stars program. Both are optional—using and sharing the project helps too.
💻💖☕ by Waren Gonzaga | YHWH 🙏