DOCSEARCHbyAlgolia
Submit Docs

GitHub Readme Stats

repository·master·Indexed 13 days ago

https://github.com/anuraghazra/github-readme-stats

Dynamically generate SVG cards for GitHub README files to display user statistics such as commits, stars, and top languages. Features include built-in themes, responsive light/dark mode support, and customizable cards for top languages, extra pins, and gists. Note: This project is no longer maintained; users are encouraged to use GitHub Stats Extended or GitHub Readme Stats Action for active maintenance.

Tokens
11.4K
Snippets
36
Records
46
Agent score
98%

What's inside GitHub Readme Stats

  1. Important Notice: Project Maintenance and Reliability

    master

    Maintenance Status

    This repository is no longer maintained. For an actively maintained version with additional features and improved stability, use:

    Reliability Warning

    The public Vercel instance at https://github-readme-stats.vercel.app/api is provided on a best-effort basis and may be unreliable due to GitHub rate limits and traffic spikes.

    To ensure reliable card rendering, it is recommended to:

    1. Self-host the application (on Vercel or other platforms).
    2. Use the GitHub Actions workflow to generate cards directly in your profile repository.

  2. Understand the Top Languages ranking algorithm

    master

    The ranking of languages is determined by the following formula:

    ranking_index = (byte_count ^ size_weight) * (repo_count ^ count_weight)

    By default, the card orders by byte count (size_weight=1, count_weight=0). You can adjust these weights to change how languages are ranked:

    • Order by byte count (Default): &size_weight=1&count_weight=0
    • Use both byte and repo count (Recommended): &size_weight=0.5&count_weight=0.5
    • Order by repo count: &size_weight=0&count_weight=1
    ![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&size_weight=0.5&count_weight=0.5)

  3. Implement responsive themes for Light/Dark mode

    master

    Since the server cannot detect the user's browser theme, use one of these three methods to make your card responsive:

    1. Transparent Theme: Use &theme=transparent to create a card that blends into both light and dark backgrounds.
    2. GitHub Theme Context Tags: Append #gh-dark-mode-only or #gh-light-mode-only to the end of the image URL to show specific versions based on the user's GitHub theme.
    3. HTML <picture> element: Use the <picture> tag with prefers-color-scheme media queries to switch between a dark-themed URL and a light-themed URL.
    <picture>
  <source
    srcset="https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true&theme=dark"
    media="(prefers-color-scheme: dark)"
  />
  <source
    srcset="https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true"
    media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)"
  />
  <img src="https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true" />
</picture>

  4. Deploy GitHub Readme Stats to Vercel

    master

    Self-hosting on Vercel avoids public rate limits and provides control over caching and private stats.

    Steps to deploy:

    1. Fork this repository.
    2. Go to your Vercel dashboard and click Add New... -> Project.
    3. Import your forked repository.
    4. Create a GitHub PAT (as described in the PAT guide).
    5. Add the PAT as an environment variable named PAT_1.
    6. Click deploy.

    Note for Vercel Pro users: If your instance frequently times out, you can increase the maxDuration in vercel.json, but it is advised to keep it below 30 seconds to prevent high memory usage.

  5. Apply built-in themes

    master

    You can quickly change the visual style of your card using the &theme=THEME_NAME parameter.

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

    ![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true&theme=radical)

  6. Apply themes to Repo Cards

    master

    You can customize the appearance of your Repo Cards by using the theme query parameter in the API URL. The following themes are compatible with all cards, including the Repo Card, Stats Card, Gist Card, Top Languages Card, and WakaTime Card.

    To use a theme, append &theme=THEME_NAME to your card's URL. For example, to use the radical theme, your URL would end with &theme=radical.

    https://github-readme-stats.vercel.app/api/pin/?username=YOUR_USERNAME&repo=YOUR_REPO&theme=radical

  7. Use the WakaTime Stats Card

    master

    You can display your WakaTime coding statistics in your GitHub README using the WakaTime API endpoint.

    Prerequisites:

    • Your WakaTime profile must be public. In WakaTime settings, ensure both Display code time publicly and Display languages, editors, os, categories publicly are enabled.
    • New WakaTime accounts may take up to 24 hours for stats to become visible.

    Usage: Replace username=YOUR_USERNAME in the URL with your actual WakaTime username.

    [![WakaTime stats](https://github-readme-stats.vercel.app/api/wakatime?username=YOUR_USERNAME)](https://github.com/anuraghazra/github-readme-stats)
    [![Harlok's WakaTime stats](https://github-readme-stats.vercel.app/api/wakatime?username=ffflabs)](https://github.com/anuraghazra/github-readme-stats)

  8. Use GitHub Extra Pins to pin more than 6 repositories

    master

    The GitHub Extra Pins feature allows you to bypass the standard 6-repository limit in your GitHub profile by using a dedicated API endpoint. You can customize the card using common options and specific pin options.

    Endpoint: api/pin?username={username}&repo={repo}

    Exclusive Options:

    • show_owner (boolean): Shows the repository's owner name. Defaults to false.
    • description_lines_count (number): Manually set the number of lines for the description (clamped between 1 and 3). If not specified, it adjusts automatically.
    [![Readme Card](https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats)](https://github.com/anuraghazra/github-readme-stats)

  9. Deploy GitHub Readme Stats via GitHub Actions

    master

    Because the public endpoint can be unreliable, it is recommended to self-deploy using GitHub Actions. This method generates static SVGs and stores them in your repository, avoiding per-request API calls.

    1. Create a workflow file at /.github/workflows/grs.yml in your profile repository.
    2. Use the readme-tools/github-readme-stats-action@v1 action.
    3. For private stats, pass a Personal Access Token (PAT) as a secret instead of GITHUB_TOKEN.
    4. Embed the generated SVG in your README using a local path.

    Note: This setup is best for static updates. For fresher stats, consider self-hosting a dedicated instance.

    name: Update README cards

on:
  schedule:
    - cron: "0 3 * * *"
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate stats card
        uses: readme-tools/github-readme-stats-action@v1
        with:
          card: stats
          options: username=${{ github.repository_owner }}&show_icons=true
          path: profile/stats.svg
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Commit cards
        run: |
          git config user.name "github-actions"
          git config user.email "github-actions@users.noreply.github.com"
          git add profile/*.svg
          git commit -m "Update README cards" || exit 0
          git push

  10. Apply inbuilt themes to GitHub Stats cards

    master

    You can customize the visual appearance of your cards using the theme query parameter. This allows you to change the look of the cards without manual color customization. The themes are compatible with all five card types:

    • Stats Card
    • Repo Card
    • Gist Card
    • Top Languages Card
    • WakaTime Card

    To apply a theme, append ?theme=THEME_NAME to your card URL.

    ![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&theme=dark&show_icons=true)

  11. Use the Top Languages Card to show most used languages

    master

    The Top Languages card displays a user's most frequently used languages based on GitHub metrics.

    Important Limitations & Warnings:

    • Public Repos Only: By default, it only shows results from public repositories. To include private repositories, you must deploy your own instance with a GitHub API token.
    • Non-forked Repos Only: It only counts usage within your own non-forked repositories; it does not include contributions to other users' or organizations' repositories.
    • Data Limit: Currently limited to the first 100 repositories due to GitHub API constraints.
    • Encoding: Language names and custom_title must be URI-escaped (e.g., c++ becomes c%2B%2B).

    Endpoint: api/top-langs?username={username}

    [![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra)](https://github.com/anuraghazra/github-readme-stats)

  12. Create a GitHub Personal Access Token (PAT) for self-hosting

    master

    To deploy your own instance of GitHub Readme Stats, you must create a GitHub Personal Access Token (PAT). The required scopes depend on whether you use a Classic or Fine-grained token. Selecting the correct scopes is essential if you want to display private contributions on your cards.

    #### Classic token scopes:
- `repo` 
- `read:user` 

#### Fine-grained token scopes (Repository permission):
- `Commit statuses`: read-only
- `Contents`: read-only
- `Issues`: read-only
- `Metadata`: read-only
- `Pull requests`: read-only