GitHub Readme Stats

Dynamically generated GitHub stats cards for your README.

Quick Start

Add this to your README (replace YOUR_USERNAME with your GitHub username):

``markdown
!GitHub Stats
`

> Note: Replace YOUR-INSTANCE.WORKERS.DEV with your deployed Cloudflare Workers instance URL and YOUR_USERNAME with your GitHub username.

---

Important Notes

> [!IMPORTANT]
> The GitHub API allows 5k requests per hour per account. Public instances may hit rate limits. We use caching to prevent this. For better control, deploy your own instance.

> [!WARNING]
> By default, cards only show statistics from public repositories. To include private repository statistics, deploy your own instance with a GitHub Personal Access Token.

---

GitHub Stats Card

Display your GitHub statistics including stars, commits, pull requests, and more.

$3

`markdown
!GitHub Stats
`

$3

| Parameter | Description | Example |
|-----------|-------------|---------|
| username | GitHub username (required) | NAME |
| theme | Theme name | dark, radical, merko, etc. |
| hide | Hide specific stats | stars,commits,prs |
| show | Show additional stats | reviews,discussions_started |
| show_icons | Display icons | true |
| hide_border | Hide card border | true |
| bg_color | Background color (hex) | 1a1b27 |
| title_color | Title color (hex) | fff |
| text_color | Text color (hex) | 9f9f9f |
| border_color | Border color (hex) | e4e2e2 |
| locale | Language | en, es, fr, etc. |
| cache_seconds | Cache duration (21600-86400) | 21600 |

$3

| Parameter | Description | Default |
|-----------|-------------|---------|
| hide_title | Hide card title | false |
| hide_rank | Hide rank badge | false |
| rank_icon | Rank icon style | default, github, percentile |
| card_width | Card width in pixels | 500 |
| include_all_commits | Count all commits (not just current year) | false |
| commits_year | Filter commits by year | Current year |
| exclude_repo | Exclude repositories | Comma-separated list |
| custom_title | Custom card title | GitHub Stats |
| number_format | Number format | short (e.g., 6.6k) or long (e.g., 6626) |

$3

Hide specific stats:
`markdown
!GitHub Stats
`

Show icons:
`markdown
!GitHub Stats
`

Use a theme:
`markdown
!GitHub Stats
`

Custom colors:
`markdown
!GitHub Stats
`

$3

Popular themes include: dark, radical, merko, gruvbox, tokyonight, onedark, cobalt, synthwave, highcontrast, dracula, transparent, and more.

See all available themes for the complete list.

$3

Use GitHub's theme context tags for automatic dark/light mode:

`markdown
![GitHub Stats Dark](https://github.com/YOUR_USERNAME)
![GitHub Stats Light](https://github.com/YOUR_USERNAME)
`

---

Top Languages Card

Display your most frequently used programming languages.

$3

`markdown
!Top Languages
`

$3

| Parameter | Description | Default |
|-----------|-------------|---------|
| layout | Layout style | normal, compact, donut, donut-vertical, pie |
| langs_count | Number of languages to show (1-20) | 5 |
| hide | Hide specific languages | Comma-separated list |
| exclude_repo | Exclude repositories | Comma-separated list |
| size_weight | Weight for byte count in ranking | 1 |
| count_weight | Weight for repo count in ranking | 0 |
| stats_format | Display format | percentages or bytes |
| hide_progress | Hide progress bars | false |

$3

Compact layout:
`markdown
!Top Languages
`

Donut chart:
`markdown
!Top Languages
`

Show more languages:
`markdown
!Top Languages
`

Hide specific languages:
`markdown
!Top Languages
`

$3

Languages are ranked using:
`
ranking_index = (byte_count ^ size_weight) * (repo_count ^ count_weight)
`

- Default (size_weight=1, count_weight=0): Orders by byte count
- Recommended (size_weight=0.5, count_weight=0.5): Uses both byte and repo count
- Repo-based (size_weight=0, count_weight=1): Orders by repo count

---

Repository Card

Pin additional repositories beyond GitHub's 6-repo limit.

$3

`markdown
!Repository Card
`

$3

| Parameter | Description | Default |
|-----------|-------------|---------|
| show_owner | Show repository owner | false |
| description_lines_count | Number of description lines (1-3) | Auto |

$3

`markdown
!Repository Card
`

---

Gist Card

Display GitHub Gists in your README.

$3

`markdown
!Gist Card
`

$3

| Parameter | Description | Default |
|-----------|-------------|---------|
| show_owner | Show gist owner | false |

$3

`markdown
!Gist Card
`

---

WakaTime Card

Display your WakaTime coding statistics.

> [!WARNING]
> Your WakaTime profile must be public. Enable both "Display code time publicly" and "Display languages, editors, os, categories publicly" in your WakaTime settings.

$3

`markdown
!WakaTime Stats
`

$3

| Parameter | Description | Default |
|-----------|-------------|---------|
| layout | Layout style | default, compact |
| langs_count | Limit number of languages | All languages |
| hide_progress | Hide progress bars | false |
| display_format | Display format | time or percent |
| api_domain | Custom API domain | wakatime.com |

$3

`markdown
!WakaTime Stats
`

---

Deployment

$3

1. GitHub Personal Access Token (PAT)
- Go to GitHub Settings > Developer Settings > Personal Access Tokens
- Create a new token (classic) with repo and read:user scopes
- Copy the token

$3

1. Fork this repository

2. Install dependencies:
`bash
pnpm install
`

> Note: This project uses pnpm as the package manager. If you don't have pnpm installed, you can install it with npm install -g pnpm.

3. Configure wrangler.toml:
`toml
name = "github-readme-stats"
main = "src/worker.ts"
compatibility_date = "2025-12-04"
compatibility_flags = ["nodejs_compat"]

[observability]
enabled = true
head_sampling_rate = 1

[observability.logs]
enabled = true
head_sampling_rate = 1
persist = true
invocation_logs = true

[observability.traces]
enabled = true
persist = true
head_sampling_rate = 1

[vars]
PAT_1 = "your_pat_token_here"
`

> [!WARNING]
> For production, use Cloudflare secrets instead of [vars]:
> `bash
> wrangler secret put PAT_1
> `

4. Deploy:

Option A: Manual deployment
`bash
npx wrangler deploy
`

Option B: GitHub Actions (Recommended)

Set up the following secrets in your GitHub repository:
- CLOUDFLARE_API_TOKEN: Your Cloudflare API token (create at Cloudflare Dashboard > My Profile > API Tokens)
- CLOUDFLARE_ACCOUNT_ID: Your Cloudflare Account ID (found in the right sidebar of your Cloudflare dashboard)
- PAT_1: Your GitHub Personal Access Token (optional, if not set in wrangler.toml)

The workflow will automatically deploy on every push to main/master branch, or you can trigger it manually from the Actions tab.

5. Your instance will be available at:
`
https://your-worker-name.your-subdomain.workers.dev
`

6. Update your README URLs to use your new domain!

$3

Configure your instance using these environment variables:

| Variable | Description | Example |
|----------|-------------|---------|
| PAT_1, PAT_2, etc. | GitHub Personal Access Tokens | ghp_... |
| CACHE_SECONDS | Cache duration in seconds (0 to disable) | 21600 |
| WHITELIST | Comma-separated allowed usernames | user1,user2 |
| GIST_WHITELIST | Comma-separated allowed Gist IDs | id1,id2 |
| EXCLUDE_REPO | Comma-separated repositories to exclude | repo1,repo2 |
| FETCH_MULTI_PAGE_STARS | Fetch all starred repos | true or false |

> [!WARNING]
> Redeploy your instance after changing environment variables for changes to take effect.

$3

Use GitHub's Sync Fork feature or the pull package to keep your fork up to date.

---

Configuration

$3

The cards support multiple languages. Set the locale parameter to use:

ar, az, bn, bg, my, ca, cn, zh-tw, cs, nl, en, fil, fi, fr, de, el, he, hi, hu, id, it, ja, kr, ml, np, no, fa, pl, pt-br, pt-pt, ro, ru, sa, sr, sr-latn, sk, es, sw, se, ta, th, tr, uk-ua, ur, uz, vi

Example:
`markdown
!GitHub Stats
`

$3

Default cache durations:
- Stats card: 24 hours
- Top languages card: 144 hours (6 days)
- Repository card: 240 hours (10 days)
- Gist card: 48 hours (2 days)
- WakaTime card: 24 hours

Override with cache_seconds parameter (min: 21600, max: 86400) or set CACHE_SECONDS environment variable.

$3

Use HTML with align attribute:

`html






``

---

API Documentation

For comprehensive API documentation including all endpoints, parameters, response formats, error handling, and examples, see API.md or API Documentation.

OpenAPI Specification: The API is also available as an OpenAPI 3.1.0 specification in openapi.yaml. You can use this with tools like:
- Swagger UI for interactive API exploration
- Postman for API testing
- Code generators for client SDKs
- API documentation generators

---

Support

Contributions are welcome! If you find this project useful:

- ⭐ Star the repository
- 🐛 Report bugs
- 💡 Suggest features
- 📖 Improve documentation

Made with ❤️ and JavaScript.