GitHub Readme Statsの動的SVGカード：プロフィール表示を組み立てる仕組み

公開インスタンスとリポジトリについて

GitHub Readme Statsは、ユーザーのGitHub統計情報を表すSVG画像を生成するJavaScriptプロジェクトで、GitHubプロフィールのREADMEに埋め込むことを目的としています。公開インスタンスはVercel上でホストされており、URLは https://github-readme-stats.vercel.app です。リポジトリはMITライセンスです。リポジトリのメタデータによると、スター数は79,816、フォーク数は36,203、デフォルトブランチはmasterです。READMEの冒頭のタグラインは「あなたのREADMEに動的に生成されるGitHub統計」です。

5つのカードタイプ、各エンドポイント

READMEには5つの異なるカードタイプが記載されています。GitHub Stats Cardはapiエンドポイントとusernameパラメータを使用し、スター、コミット、プルリクエスト、イシュー、コントリビューションを表示し、加えて100からグローバルパーセンタイルを引いた値を示すランクサークルを表示します。Top Languages Cardはapi/top-langsを使用し、ユーザー自身の非フォークリポジトリで最もコードが多い言語を表示しますが、スキルレベルを示すものではないと注記されています。GitHub Extra Pinsはapi/pinを使用してリポジトリカードを表示し、GitHubが通常許可する6つ以上のリポジトリをピン留めできます。GitHub Gist Pinsはapi/gistを使用してGistカードを表示します。最後に、WakaTime Stats Cardはapi/wakatimeを使用して公開WakaTimeプロフィールのコーディングアクティビティを表示し、「コード時間を公開する」と「言語、エディタ、OS、カテゴリを公開する」の両方が有効である必要があります。各エンドポイントはMarkdownに直接埋め込めるSVGを返します。

URLパラメータによるカスタマイズ

すべてのカードは、色、背景、枠線、テーマ、角丸、ロケール、cache_secondsのための共通のクエリパラメータを受け入れます。背景色は単色または「角度,開始色,終了色」の形式のグラデーションにできます。カード固有のオプションもあります。統計カードでは、個別の統計を非表示にしたり、レビューやマージされたPRなどの追加項目を表示したり、すべてのコミットを含めたり、カスタムタイトルを設定したり、ランクアイコンを変更したりできます。トップ言語カードは、normal、compact、donut、donut-vertical、pieの5つのレイアウトと、size_weightとcount_weightを使用した言語ランキングアルゴリズムを提供し、推奨設定は0.5と0.5です。テーマは内蔵されていますが、READMEはメンテナンス負荷を減らすために新しいテーマの追加を一時停止したと述べています。カスタムタイトルと言語名はURIエスケープする必要があります。

データソース、キャッシュ、既知の制限

デフォルトでは、すべてのカードは公開リポジトリのデータのみを使用します。プライベートなコントリビューションを表示するには、GitHub Personal Access Tokenを使用して自分のインスタンスをデプロイする必要があります。公開インスタンスはベストエフォートとされており、レート制限やトラフィックの急増により信頼性が低い可能性があります。安定性を向上させるためにキャッシュが使用されており、カードタイプごとのデフォルトのキャッシュ時間は異なります：統計とWakaTimeは24時間、トップ言語は144時間、ピンは240時間、Gistは48時間です。トップ言語カードはGitHub APIの制限により最初の100リポジトリのみを調べます。統計カードのランクは、指数分布と対数正規分布に基づく加重パーセンタイルであり、ランクはSからCで、日本の学業成績評価システムに従っています。言語統計アルゴリズムは、ranking_index = (byte_count ^ size_weight) * (repo_count ^ count_weight) という式を使用し、デフォルトの重みはsize_weight=1、count_weight=0です。READMEはまた、特定のプルリクエストの後、公開インスタンスは1時間あたり5k以上のリクエストを処理できるはずであると述べていますが、ベンチマークは提供していません。

自分のインスタンスをデプロイする

READMEは信頼性の高いカードのためにセルフデプロイを推奨しています。2つの方法が文書化されています。1つ目はGitHub Actionsを使用して、スケジュールに従って静的SVGを生成し、プロフィールリポジトリにコミットする方法で、公開データにはGITHUB_TOKEN、プライベート統計にはPATを使用します。2つ目はVercelまたは他のプラットフォームでのセルフホスティングで、特定のスコープを持つPATが必要です。CACHE_SECONDS、WHITELIST、GIST_WHITELIST、EXCLUDE_REPO、FETCH_MULTI_PAGE_STARSなどの環境変数が動作を制御します。例えば、WHITELISTはインスタンスへのアクセスを許可するGitHubユーザー名のカンマ区切りリストであり、EXCLUDE_REPOはURLで名前を公開せずにリポジトリを統計から除外します。READMEはまた、非Vercelプラットフォームのサポートは限られており、環境変数を変更した後は再デプロイする必要があると警告しています。

メンテナンス状況とライセンス

READMEの冒頭には、このリポジトリがもはやメンテナンスされていないという注意書きがあります。ユーザーは、追加機能と改善された安定性を備えた積極的にメンテナンスされているフォークであるGitHub Stats Extended、またはGitHub Readme Stats Actionを利用するよう指示されています。既存のドキュメントは参照用にのみ保持されています。このプロジェクトはMITライセンスの下で提供されており、著作権表示を含めることを条件に、コピーの使用、複製、変更、結合、公開、配布、サブライセンス、販売を許可します。ライセンスはまた、保証と責任を否認しています。READMEには、キャッシュのデフォルトと1時間あたり5kリクエストの処理に関する注記以外に、セキュリティ保証、サポート義務、パフォーマンスベンチマークは記載されていません。

編集部の結論

GitHubプロフィールに言語別統計やコミットカードを置きたい人には用途が明確です。メンテナンス停止の記載があるため、最新GitHub APIや自前デプロイを長期運用の前提にする場合は慎重さが要ります。まず必要カードのURLパラメータを固定し、生成SVG、API制限時の応答、Vercel設定を確認してください。

公式情報源

1. Official documentation
2. Official README
3. Project repository