GitHub widgets by Kretoffer

Dynamic SVG widgets for GitHub, ready to embed into your README
Explore the docs »

Report Bug · Request Feature

Quick Start

Open the official widget builder at github-widgets.kretoffer.com, pick a widget, customize it, and copy the generated snippet into your README.md. That's it.

Widgets

Issues Roadmap

A roadmap card generated from repository issues, with status badges (open/closed), labels and a custom heading.

![Issues Roadmap](https://github-widgets.kretoffer.com/api/issues-list/{GITHUB_USERNAME}/{GITHUB_REPO})

Parameters

Parameter	Default	Description
count	20	Number of issues to show
header-text	Roadmap	Card heading text
width	700	Card width in px, 300 – 1600
theme	default	Predefined widget theme
labels	true	Show labels on issue card
closed	false	Show closed issues
animation-duration	0.7	Time in seconds (s) for one issue to appear, not the whole animation. Issues appear one by one; total animation time = animation-duration × number of issues. 0 — no animation

![Issues Roadmap](https://github-widgets.kretoffer.com/api/issues-list/kretoffer/github-widgets?count=2&header-text=My%20Roadmap&width=500&theme=default&closed=true)

Self-hosting

Run your own instance with Docker:

docker run -e GITHUB_TOKEN=your_token -p 8000:8000 ghcr.io/kretoffer/github-widgets:latest

Required environment variables (see .env.example):

• GITHUB_TOKEN — GitHub token used to fetch repository data

Then point your embeds to your own host instead of the public instance.

Development

uv sync --all-groups
uv run github-widgets

Quality checks:

uv run ruff check
uv run pyright
uv run pytest

Project layout:

src/
├── api/                 # FastAPI routes
├── schemas/             # Pydantic models
├── templates/           # SVG templates
└── tools/               # GitHub API and render logic

License

License