Every project page on the internet wants to brag about its GitHub star count — and rightly so. A star count is the cleanest single signal a developer-audience visitor reads as "this is worth my time." Putting that count on your website (not just your README) is one of the highest-ROI 60-second additions you can make to an OSS landing, a docs site, a personal portfolio, or a SaaS marketing page.

This guide walks every option — the Shields.io badge most developers know, the GitHub native counter, and a one-line drop-in pill — and shows which one to pick for which use case. If you're skimming: FeedPulse's free GitHub Stars badge is the lightest, fastest path. No API key, no signup, no re-fetch tax on every page load.

What is a GitHub Stars badge?

A GitHub Stars badge is a small visual element you embed on a third-party website that shows your repo's current star count, pulled live from GitHub's API. The number updates as your repo gains or loses stars.

GitHub exposes the star count through its public REST API at https://api.github.com/repos/{owner}/{repo}. The stargazers_count field on the response is the number you display. The endpoint is open and doesn't require authentication for public repos.

There are two ways to render this number: as an SVG image (the Shields.io approach) or as live text inside a small HTML pill. Both work; their performance and customization characteristics differ.

Why your website needs one

1. Instant credibility for developer audiences

A star count is the single most-recognized OSS trust signal among developers. Search-engine clicks land on your site for 2-5 seconds before the visitor decides whether you're worth their time; a visible star count in that window converts skim-readers to readers far better than a paragraph of prose.

2. Social proof that updates itself

A static "starred by 4,200 developers" sentence is fine, but every visitor wonders if that number is current. A live badge collapses the doubt instantly.

3. SEO body content

For a thin page (a project's marketing landing, a side-project README mirror), a star-count widget adds visible, unique on-page content that helps search rankings — particularly for "alternatives to X" pages where the SERP rewards comparable freshness signals across pages.

4. Natural pairing with other dev-audience widgets

If you ship an npm package, your visitor is looking for both the star count and the weekly download count before they choose to install. Pair the two badges side by side; conversion typically lifts 10-20% versus showing only one. Full strategy in our npm Downloads how-to.

Method 1: Shields.io SVG badge (the developer default)

The most-used solution. Shields.io renders an SVG badge live on every page load:

<img alt="GitHub stars" src="https://img.shields.io/github/stars/owner/repo?style=flat">

Pros: Universally familiar, looks at home in a README or docs page, no JS to run. Cons:

• The SVG is re-fetched on every page load — there's no client-side cache, so a popular page hammers Shields.io's CDN.
• Shields.io's free tier has a soft rate limit; pages with multiple Shields badges intermittently 503.
• The badge is styled to match Shields' canonical pill — not your site palette.
• No click-through behavior; you'd need to wrap it in an <a> tag yourself.

Best fit: READMEs, technical docs that look like docs, anywhere the Shields style is "the style".

Method 2: GitHub's "buttons" script (the official approach)

GitHub publishes a tiny JS library for embedding follow / star / fork buttons:

<a class="github-button" href="https://github.com/owner/repo" data-show-count="true">Star</a>
<script async defer src="https://buttons.github.io/buttons.js"></script>

Pros: First-party, includes an inline "Star" button that opens the GitHub starring flow. Cons:

• The buttons.js library is ~16 KB gzipped and adds ~150-200 ms of script evaluation.
• The visual is locked to GitHub's house style (the gray "Star | 4.2k" pill); no theming.
• The button is rendered inside an iframe sandbox per origin, which adds CORS round-trips and another 100-200 ms.

Best fit: pages where you want the inline "Star" CTA itself (clicking it opens the star flow), not just the count.

Method 3: Custom-built (the hard way)

GitHub's API endpoint is public and unauthenticated for public repos:

curl https://api.github.com/repos/microsoft/vscode

You can call this from your own backend, cache the response for 5-30 minutes, and render the result however you want.

The catch: the unauthenticated API rate limit is 60 requests/hour per IP. If your widget hits the API directly from the browser, every page-load-from-a-different-visitor consumes one of those 60. You'll get rate-limited within minutes on any moderately-trafficked page. You'd need a server-side proxy, retry-with-backoff, theming you maintain yourself.

For a single site, rarely worth it. For a SaaS or a directory, it might be.

Method 4: The one-line drop-in badge (recommended)

This is what we built FeedPulse's free GitHub Stars badge to be. One line of HTML, ~4 KB gzipped, picks up your repo's star count live, renders a small embeddable pill with seven theme options.

<script async
  src="https://feed-pulse.com/api/embed/github-stars.js?repo=owner/repo&theme=github">
</script>

What you get:

• ★ 4,234 pill in GitHub's own dark-blue (or 6 alternative themes — obsidian, ivory, indigo, emerald, slate, transparent).
• Live count cached server-side for 6 hours so your visitors never trigger a GitHub API call directly. (Shared cache across all FeedPulse embedders means one upstream call serves thousands of pages.)
• Click-through opens the repo on GitHub.
• Auto-truncates large counts (★ 4.2k, ★ 12.4M).
• Lighthouse 100/100/100/100 verified on the badge's own landing page.
• 12 locales for the "stars" suffix (estrellas / étoiles / звёзд / 星 / نجمة / etc.).

Open the customizer, enter your owner/repo slug, pick a theme, copy the snippet. No account, no email, no upgrade screen.

Embedding on specific platforms

The snippet is plain HTML and works on any platform that lets you paste a <script> tag.

WordPress

• Gutenberg: Custom HTML block. Paste. Done.
• Classic editor: switch to Text tab, paste, save.
• Sidebar / footer: Appearance → Widgets → Custom HTML widget. Paste.
• Strict installs that strip <script>: Code Snippets or Insert Headers and Footers plugin.

Static-site generators (Hugo, Jekyll, Astro, Next.js, Eleventy)

Drop the snippet into your layout template (right before </body> so it doesn't block first paint).

Docusaurus / VuePress / MkDocs

Inside your homepage .md / .mdx file: most MDX-aware generators let you paste raw HTML inline. The snippet works without changes.

Shopify

Settings → Theme code → theme.liquid. Paste before </body>.

Webflow

Page settings → Custom Code → Before </body> tag. Paste. Publish.

Ghost / Carrd / Framer

• Ghost: Code Injection → Site Footer. Paste.
• Carrd: add an Embed element, paste.
• Framer: add a Custom Code block, paste, position.

README.md

GitHub READMEs strip <script> tags, so the JS pill doesn't work there directly — but Shields.io's badge does. Use FeedPulse's pill on your website; use Shields.io's SVG on your README. Best tool for each surface.

Performance comparison

Lighthouse mobile, fast 3G, Moto G4 emulation, against a clean 100/100/100/100 landing.

The Shields.io approach is fastest on first byte but introduces a separate origin that fails periodically. The FeedPulse drop-in is functionally tied at parity but with predictable uptime (the cache is shared across all embedders, so the upstream call rate is constant regardless of total embed count).

Caching and freshness

For a non-trending repo, fresh-within-6-hours is plenty. FeedPulse caches the count server-side for 6 hours per repo. The cache key is the owner/repo slug, so all embedders of the same repo share one upstream call.

When the cache misses, the widget hits GitHub's public API with an unauthenticated request — which has a 60/hour limit per IP. Because the request comes from FeedPulse's IP (not your visitor's), and the per-repo cache lasts 6 hours, the practical headroom is effectively unlimited.

Privacy + GDPR

One server-side proxied request per 6-hour window. No cookies, no fingerprinting, no visitor IP leaks to GitHub. GDPR-safe by default. Full data flow in the GitHub Stars FAQ.

Common issues

"The badge shows ★ — instead of a number." Either the repo doesn't exist, is private, or the slug has a typo. Double-check owner/repo matches https://github.com/owner/repo exactly.

"Numbers look truncated." Counts ≥1,000 render as 4.2k; counts ≥1,000,000 render as 4.2M. Intentional — keeps the pill width predictable inside narrow layouts. If you need long-form, file a widget idea request for a format=full toggle.

"My count jumped 50 stars but the badge still shows the old count." 6-hour cache window. The new count will appear at the next refresh. Append &v=2 to the snippet's src to bust the per-embedder cache lookup if needed.

What to pair with the GitHub Stars badge

GitHub Stars solo is fine, but the developer audience reads multiple signals at once. Stack with:

• Free npm Downloads badge — if you ship a package, side-by-side stars + weekly downloads tells the full story. Full how-to.
• Free Discord server widget — proves you have a community, not just code. Guide.
• Free YouTube live widget — if you stream development sessions, the LIVE pill appears auto when you start.

Together: "people like it" (stars) + "people use it" (downloads) + "people talk about it" (Discord) + "people watch it being built" (YouTube live). That's a complete momentum signal.

Wrapping up

A GitHub Stars badge is the developer-audience equivalent of social proof. The Shields.io SVG is the canonical README pick. The FeedPulse drop-in is the fastest path to a styled, performant, themable badge on your website. Both are free; pick by where the badge lives.

If you want a live badge on your site in the next 60 seconds, open the customizer, paste owner/repo, copy the snippet. Done.