Engive GitHub Widget — Docs
7 personalized, trustworthy GitHub cards and 7 themes. SVG image embeds need no JavaScript on the destination. Public preview is separate from authenticated activation and saving.
Quick start — GitHub README
- Choose a handle and card in the personalized playground. The public example is @ankurhalder.
- For your own persistent embeds, sign in at /user/widgets, sync GitHub data, and save settings. Configure coding-profile handles there if needed. No admin access is required.
- Copy your generated Markdown or HTML image snippet, then verify installation: open the SVG URL directly and preview your README after saving it.
<img src="https://www.ankurhalder.com/api/widget/ankurhalder/stats.svg?theme=glass-dark&cardWidth=520" alt="Ankur Halder's GitHub Stats" />
Preview → customize → embed
A card that follows your work.
Try a public handle without signing in. Registration keeps your widget live.
SVG works in GitHub READMEs. The full playground also offers HTML images and JavaScript for websites.
7 configurable cards
Each returns SVG. The common styling parameters below are accepted by card endpoints; visible effects depend on each layout. Card-specific controls and the separate badge are not interchangeable.
| Endpoint | What it shows |
|---|---|
/api/widget/[username]/stats.svg | Profile, stars, language shares, and observed activity from the available snapshot. |
/api/widget/[username]/top-languages.svg | Available language shares. Public preview uses a repository primary-language sample, not complete language bytes. |
/api/widget/[username]/streak.svg | Current and longest observed streak within the available activity window, not a guaranteed all-time longest streak. |
/api/widget/[username]/streak-trophy.svg | Observed streaks, activity, stars, and repositories with a computed rank badge; not a GitHub-issued rating. |
/api/widget/[username]/repos.svg | Selected repositories with stars, forks, primary language, and descriptions. |
/api/widget/[username]/contributions.svg | Activity heat map. A public-event sample is not complete annual contributions, including private activity. |
/api/widget/[username]/coding-profiles.svg | LeetCode solved counts, Codeforces rating, and Stack Overflow reputation when the relevant handles are configured and providers respond. |
/api/widget/[username]/views.svg is a separate render-count badge. Its only style parameter is theme=light or theme=dark (default dark), not the card presets or width controls. JSON at /api/widget/[username]/views returns { u, n }. It reports sampled JS render events, not human views or README image impressions.
/widget/example/ankurhalder/[endpoint].svg renders the same cards from a build-time snapshot of that account's public data, so a demo keeps working on an instance where the handle has no registration. It accepts the same style parameters, is always labelled as sample data, never reads a database or a provider, and is not an endpoint to embed — your own handle needs the /api/widget/… URL above.
Themes
7 card presets. Select theme, then override supported colors. Aurora uses a static gradient in SVG, not animation.
glass-darkglass-lightauroraneondraculacatppuccinsolarized
URL parameter reference — common card styles
Defaults below come from the settings schema; presets and saved settings can override them. Invalid or unsupported URL values are ignored. Prefer platform fonts for portability; SVG appearance is not guaranteed identical across image proxies and platforms.
| Parameter | Type / Range | Default | Description |
|---|---|---|---|
| theme | preset | glass-dark | One of glass-dark, glass-light, aurora, neon, dracula, catppuccin, solarized. glass and light are legacy aliases. |
| cardWidth | 240–800 | 320 | SVG width in pixels; numeric query values are clamped to the supported range. |
| backgroundColor | color | #0d1117 | Background override. Use hex or numeric rgb()/rgba(); URL-encode # as %23. Named colors and CSS URLs are not supported. |
| accentColor | color | #58a6ff | Accent override; theme supplies colors when not overridden. |
| textColor | color | #e6edf3 | Primary text override. |
| textMutedColor | color | rgba(230, 237, 243, 0.6) | Secondary text override. |
| borderColor | color | rgba(255, 255, 255, 0.08) | Border color override. |
| borderWidth | 0–4 | 1 | Border thickness in pixels. |
| borderStyle | solid | dashed | dotted | double | solid | Accepted style setting; visual support depends on the renderer. Web HTML supports CSS borders. |
| borderRadius | 0–32 | 14 | Corner radius in pixels. |
| cardPadding | 8–36 | 18 | Inner padding where supported by the card layout. |
| fontFamily | safe font family | -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif | Prefer the default platform fonts stack. SVG does not load web fonts: custom names depend on installed fonts and sanitizer support. URL-encode spaces, quotes, and commas. |
| fontSize | 10–20 | 14 | Base font size where supported by the layout. |
| showFooter | true | false | true | Toggle the card footer where present; does not apply to the views badge. |
| shadowGlow | true | false | false | Accent glow where supported by the renderer. |
| bgGradientEnd | color | — | Optional second background color; empty disables the gradient. |
| gradientAngle | 0–360 | 135 | Gradient angle in degrees, including 0. |
Card-specific and saved-only settings
| Parameter | Type / Range | Default | Description |
|---|---|---|---|
| avatarShape | circle | rounded | square | circle | Developer card avatar; no effect on cards without an avatar. |
| showCommits | true | false | true | Developer card activity counter visibility; does not expand source coverage. |
| showStars | true | false | true | Developer card stars visibility. |
| showStreak | true | false | true | Developer card observed streak visibility. |
| showLanguages | true | false | true | Developer card language visibility. |
enableHoverTilt is a web JS interaction, not an SVG image effect. galleryVisible, leetcodeHandle, codeforcesHandle, and stackoverflowId are authenticated saved settings, not common SVG query overrides. Use /user/widgets to change them.
Examples
Compact card
Dracula streak
Hide brand footer
Platform font stack + radius
Gradient background
Choose the format for your destination
- Markdown / HTML image: SVG images for GitHub READMEs and hosts allowing remote SVG. No host-page JavaScript. Blogs may sanitize HTML or proxy images; verify on your actual platform.
- Web HTML / JS: the loader and widget container require JavaScript. Use on portfolios and documentation sites allowing scripts, not GitHub READMEs or email.
- Raw SVG URL: the endpoint is the artifact itself. Paste the URL wherever an image source is accepted — a CSS background, a docs site, a chat message that allows remote images. It renders with system fonts only and is not a page you can navigate.
- PNG download: use the playground download utility for email, slides, or hosts rejecting SVG. This is a static snapshot, not an auto-refreshing PNG endpoint. Test email-client image support.
- Share URL: opens the personalized playground configuration; it is not an image URL and does not activate an account.
https://www.ankurhalder.com/api/widget/ankurhalder/stats.svg?theme=glass-dark&cardWidth=520
Data source, as-of time, and freshness
Distinguish synced snapshots from public live-preview data. Public-event samples cover a limited window; primary-language samples describe available repositories, not complete byte totals. These are not complete annual contributions or private history, and longest observed streak is not necessarily the actual all-time longest streak. A synced label alone does not guarantee full provider coverage.
Use the source and as-of timestamp where provided; if absent, freshness is unknown. The existing daily scheduled sync updates owner data only. Other users should sync through /user/widgets; there is no promise of automatic daily refresh for all accounts.
Cache-Control: public, s-maxage=86400, stale-while-revalidate=172800
A CDN may cache a successful response for 24 hours and serve stale responses during the 172800-second revalidation window. This is not a freshness guarantee or indefinite outage protection: a cache miss, expiry, or provider outage may leave an image unavailable. Host proxies can add their own caching.
Analytics and retention
The views badge reports sampled JS renders, not verified human views, unique visitors, installations, or all SVG/README loads. Sampling is configurable (default 25%); DNT/GPC suppress tracking. Deduplication currently permits at most one event per username, widget, and daily client IP hash within each hour. Clients sharing an IP can be grouped together. Rate limits, queue loss, and outages can reduce counts.
Impression events store a daily salted IP hash and referrer origin, not the full referrer path. Their configured retention is 30 days via a MongoDB TTL index; expiry is asynchronous and depends on the index being installed. Profile snapshots and saved settings are stored separately and do not share that 30-day TTL.
Advanced: JS embed for third-party sites (GitHub strips scripts)
The web HTML export uses /widget/embed.js to fetch JSON and render a container. It requires JavaScript and appropriate CSP script-src and connect-src permissions. Optional web fonts also need their font/style origins allowed. Copy the playground export to preserve customized settings.
<script src="https://www.ankurhalder.com/widget/embed.js" data-username="ankurhalder" data-engive-widget="loader" defer ></script> <div class="engive-github-widget" data-widget="developer-card"></div>
Troubleshooting and installation check
- 404 / not_registered: check the handle and endpoint, sign in to /user/widgets, activate and sync. Missing coding-profile data needs configured provider handles. Public preview is not activation.
- 429: respect
Retry-Afterbefore retrying; do not repeatedly reload or generate new query variations. - Unavailable or old data: check source/as-of time, run an account sync, and allow cache and host-proxy windows. During an outage, retry later; stale protection is finite.
- Blank image: open the generated SVG URL directly and inspect status/content type. Check
img-src, remote image blocking, proxy rules, and SVG support. Use PNG if the destination rejects SVG. - JS or iframe blocked: inspect browser console/network errors and the destination CSP. Some hosts render third-party cards only inside an iframe; the SVG URL is the card either way. GitHub and email are image destinations, not script/frame destinations.
- Check installation: save the snippet in the real destination, confirm the correct username and card, and recheck in light and dark mode. Analytics may not move when an SVG loads.
FAQ
How do I enable my own cards?
Preview publicly, then sign in at /user/widgets, sync your GitHub data, and save settings. No admin access is required. Activation and public preview are separate.
Does it work in email signatures?
SVG support varies by email client. Use the PNG download utility for a static snapshot and verify the image in your email client; it will not automatically refresh.
How often does data refresh?
Check source and as-of time. The existing daily scheduled sync covers owner data only, not every user's automatic refresh. Cache age is not GitHub data age.
What happens during an outage?
An existing cache may serve an older image within its stale window. Cache misses, expired data, or unavailable providers can return an error; availability is not guaranteed.