GitHub Readme Stats: Thẻ Thống Kê Hồ Sơ GitHub Động

Thẻ thống kê hồ sơ GitHub được tạo động

GitHub Readme Stats là một serverless API tạo thẻ SVG thống kê GitHub, ngôn ngữ dùng nhiều nhất, hoặc repo được ghim, để nhúng vào README dạng markdown. Bạn trỏ thẻ <img> tới một endpoint như api/pin hay api/top-langs kèm username trên URL, service sẽ trả về thẻ render sẵn. Nó còn có thẻ WakaTime cho thời gian code và ghim Gist, dùng chung cách truyền tham số qua URL.

Các loại thẻ có sẵn và những gì chúng theo dõi

• ✓Thẻ stats gồm commit, sao (star), PR, issue, và số người theo dõi, có thể ẩn hoặc thêm từng mục qua tham số &hide= và &show=.
• ✓Xếp hạng chữ (S đến C) tính từ percentile có trọng số trên commit, PR, review, issue, sao, và follower, dùng phân phối exponential và log-normal — công thức chính xác nằm trong src/calculateRank.js.
• ✓Thẻ Top Languages với năm layout — normal, compact, donut, donut-vertical, và pie — cùng tham số size_weight/count_weight để xếp hạng theo byte, số repo, hoặc kết hợp cả hai.
• ✓Thẻ ghim repo vượt giới hạn 6 repo ghim mặc định của GitHub, và thẻ ghim Gist riêng, cả hai dùng chung dạng endpoint api/pin và api/gist.
• ✓Thẻ WakaTime cho thống kê thời gian code, lấy từ một profile WakaTime công khai.
• ✓Bộ theme dựng sẵn (dark, radical, merko, gruvbox, tokyonight, onedark, cobalt, synthwave, highcontrast, dracula, và nhiều theme khác) cùng khả năng override màu hex cho từng phần tử.
• ✓Text trên thẻ có sẵn nhiều locale ngoài tiếng Anh, chọn bằng một tham số &locale= duy nhất.

Thêm thẻ thống kê vào README GitHub của bạn

Nhúng một thẻ chỉ tốn một dòng markdown: một thẻ ảnh trỏ tới https://github-readme-stats.vercel.app/api?username=tencuaban, đổi thành api/top-langs, api/pin, hay api/gist tùy loại thẻ muốn dùng. Mọi thuộc tính hiển thị đều là tham số trên query string chứ không phải file config — thêm &show_icons=true để có icon, &theme=dracula (hoặc radical, gruvbox, tokyonight, onedark, cobalt, synthwave, highcontrast, merko) để dùng theme dựng sẵn, hoặc tự chọn title_color, text_color, icon_color, bg_color, border_color bằng mã hex. Layout cũng có công tắc riêng: thẻ Top Languages nhận &layout=compact, donut, donut-vertical, hoặc pie, còn &size_weight / &count_weight cho phép xếp ngôn ngữ theo số byte, số repo, hoặc kết hợp cả hai. Để tự đổi dark/light mà không cần JavaScript, dùng hậu tố URL #gh-dark-mode-only / #gh-light-mode-only của GitHub, một thẻ <picture> với prefers-color-scheme, hoặc đơn giản là theme transparent dựng sẵn.

Tự triển khai instance riêng để tăng độ tin cậy

Instance công khai tại github-readme-stats.vercel.app là hạ tầng dùng chung, không phải thứ bạn tự cấp phát — README gọi nó là best-effort và cảnh báo có thể chậm hoặc lỗi khi gặp rate limit hoặc traffic tăng đột biến. Tự host nghĩa là fork repo rồi deploy lên Vercel của riêng bạn (hoặc host Node khác) kèm GitHub API token của chính bạn dưới dạng biến môi trường, việc này cũng giúp bạn lấy được số liệu từ private repo, vì instance công khai chỉ đọc được dữ liệu public. Bạn có thể set biến môi trường CACHE_SECONDS trên deployment riêng để cards refresh thường xuyên hơn mặc định (24 giờ cho thẻ stats, 6 ngày cho top languages, 10 ngày cho thẻ pin, 2 ngày cho thẻ gist). Lựa chọn thay thế mà maintainer đề xuất là tạo card qua GitHub Actions workflow thẳng vào profile repo, bỏ hẳn việc gọi một endpoint sống.

Active alternatives and the maintained fork

Câu hỏi thường gặp

Vấn đề mà nó giải quyết

README dạng markdown vốn là văn bản tĩnh — nó không thể chạy code hay gọi API, nên không có cách nào tự nhiên để hiện số commit sống hay một badge xếp hạng tự cập nhật. GitHub Readme Stats giải quyết đúng khoảng trống đó cho một bề mặt cụ thể: README của repo profile đặc biệt mà GitHub render ngay trên trang cá nhân, nơi lựa chọn thay thế cho một bức tường chữ cũ kỹ là một hình ảnh được server tạo lại mỗi lần có request.

Trường hợp sử dụng tốt nhất

• •Thêm thẻ stats sống vào README profile GitHub cá nhân thay vì một đoạn bio tĩnh.
• •Kết hợp thẻ WakaTime với thẻ stats để show cả hoạt động GitHub lẫn thời gian code thật trên cùng một profile.
• •Ghim nhiều repo hơn giới hạn 6 ô ghim mặc định của GitHub.
• •Nhúng biểu đồ donut hoặc pie top-languages vào README để thấy tech stack ngay lập tức.

Ai nên dùng — và ai nên bỏ qua

Đáng để gắn vào nếu bạn đã có README profile GitHub và muốn một thẻ stats mà không cần viết backend — dán một dòng markdown, chọn theme, xong. Điểm bất lợi này là thật: repo này không còn được bảo trì. Nên bỏ qua, hoặc ít nhất đừng phụ thuộc vào nó, nếu bạn cần uptime đảm bảo, số liệu private repo ngay trên endpoint công khai, hoặc các bản vá lỗi liên tục — cho những nhu cầu đó, hãy tự host hoặc chuyển thẳng sang bản fork đang được bảo trì mà chính README đề xuất. Thẻ WakaTime hay thẻ ghim có thể thêm vào sau khi đã setup xong.

Repo liên quan