最近、自分の GitHub Profile を整理していて、JavaScript や Vue、React、Docker などの技術スタックをもう少し見やすくしたいと思いました。テキストで並べるだけでも問題ありませんが、Badge（バッジ）を使うと一目で分かりやすくなります。
そこで使ってみたのが Shields.io です。URL を指定するだけで SVG 形式のバッジを生成できます。技術スタックだけでなく、npm のバージョン、GitHub Stars、CI の実行結果、独自の JSON API から取得した値なども表示できます。
今回は、自分用のメモも兼ねて、基本的な使い方から README でよく使う設定、動的バッジの作り方までまとめておきます。
1. Shields.io とは
Shields.io は、SVG 形式のステータスバッジを生成するサービスです。例えば、以下のようなものを簡単に作れます。
これらは事前に作成してアップロードした画像ではありません。img.shields.io の URL にアクセスすると、SVG 画像が返ってくる仕組みです。
参考サイト：
- Shields.io 公式サイト
- バッジ一覧・設定
- Simple Icons — ロゴの名前を調べるときに便利
2. 静的バッジの基本
まずは一番シンプルな例です。
https://img.shields.io/badge/build-passing-brightgreen
表示結果：
URL の基本形式は次のとおりです。
https://img.shields.io/badge/{label}-{message}-{color}
| 項目 | 内容 | 例 |
|---|---|---|
label | 左側に表示するラベル | build |
message | 右側に表示する文字列 | passing |
color | 右側の背景色 | brightgreen |
URL の文字列を変更するだけで、さまざまなバッジを作れます。
ここで注意したいのは、静的バッジに表示される文字列は固定値だということです。passing と書いても、実際にテストが成功していることを確認しているわけではありません。
2.1 ラベルを省略する
左右に分けず、一つの文字列だけ表示したい場合は、ラベルを省略できます。
2.2 特殊文字のエスケープ
URL を手書きするときに少し気を付けたいのが特殊文字です。特に /badge/ のパスでは - が区切り文字になるため、文字列中のハイフンをそのまま書くと意図した表示にならない場合があります。
| 表示したい文字 | URL での指定 |
|---|---|
| 半角スペース | _ または %20 |
アンダースコア _ | __ |
ハイフン - | -- |
パーセント % | %25 |
例えば、カバレッジを表示する場合は次のように書けます。
https://img.shields.io/badge/code_coverage-95%25-brightgreen
日本語なども含めて動的に URL を組み立てる場合は、必要な部分を適切に URL エンコードしておいた方が安全です。
3. クエリパラメータで見た目を変更する
基本形にクエリパラメータを追加すると、デザインやロゴを指定できます。
https://img.shields.io/badge/JavaScript-F7DF1E?style=flat-square&logo=javascript&logoColor=black
? 以降がパラメータで、複数指定する場合は & でつなぎます。
| パラメータ | 用途 | 例 |
|---|---|---|
style | バッジのスタイル | flat-square |
logo | 技術・ブランドのロゴ | javascript |
logoColor | ロゴの色 | white |
logoSize | ロゴサイズの調整 | auto |
label | 左側ラベルの上書き | framework |
labelColor | 左側の背景色 | 222222 |
color | 右側の背景色の上書き | blue |
cacheSeconds | キャッシュ時間の指定（サービス側の制約あり） | 3600 |
3.1 5 種類のスタイル
主に次のスタイルが用意されています。
個人的には、GitHub Profile には flat-square が使いやすいと思います。余計な装飾がなく、複数並べてもすっきり見えるためです。目立たせたい場所では for-the-badge も使えますが、README 内ではできるだけスタイルを統一した方が見やすくなります。
3.2 背景色を変更する
色は名前だけでなく、16 進数のカラーコードでも指定できます。
この例では labelColor=222222 で左側を暗い色にし、パス末尾の 4FC08D で右側を緑色にしています。color= パラメータで右側の色を上書きすることもできます。
4. ロゴの追加：Shields.io と Simple Icons
技術スタックのバッジを作るなら、ロゴも付けたいところです。
logo には主に Simple Icons の slug（識別名） を使います。
例えば、表示名と slug が必ず一致するわけではありません。
| 技術 | logo の値 |
|---|---|
| Vue.js | vuedotjs |
| Next.js | nextdotjs |
| Node.js | nodedotjs |
| JavaScript | javascript |
ロゴが表示されない場合は、まず Simple Icons 側で対応する slug が存在するか確認するとよいです。すべての製品・フレームワークのアイコンが登録されているわけではありません。
5. GitHub README に埋め込む
基本的には Markdown の画像構文を使うだけです。
バッジをクリックしたときに公式サイトへ移動させたい場合は、画像を Markdown リンクで囲みます。
[](https://vuejs.org/)
実際の表示：
複数のバッジを横並びにしたい場合は、同じ段落内に画像を並べれば OK です。
  
ただし、折り返しや間隔は GitHub やブログの Markdown レンダラーによって多少変わります。
6. 動的バッジ：実際のプロジェクト情報を表示する
ここまでは文字列を URL に直接指定する静的バッジでした。Stars 数や npm のバージョン、CI の結果など、変化するデータを表示したい場合は、専用の動的エンドポイントを使います。
6.1 GitHub Stars
badges/shields の部分が owner/repo です。自分のリポジトリに変更すれば、そのリポジトリの Stars 数を表示できます。
6.2 npm のバージョン
vue が npm パッケージ名です。npm に公開しているライブラリの README では特によく使います。
6.3 GitHub Actions の実行結果
以下の部分を自分のリポジトリに合わせて変更します。
OWNER：GitHub のユーザー名または組織名REPO：リポジトリ名ci.yml：実際のワークフローファイル名main：対象ブランチ
これはワークフローの実際の状態を参照します。静的バッジに passing と書くだけの場合とは違います。ファイル名やリポジトリが間違っていると、正常にステータスを取得できません。
6.4 Web サイトのステータス
指定した URL にアクセスできるかをバッジとして表示できます。ただし、ネットワーク環境やタイムアウトなどの影響も受けるため、本番環境の監視・通知ツールの代わりにはなりません。
7. JSON API の値を表示する：Dynamic JSON Badge
Shields.io に用意されている GitHub や npm のエンドポイントだけでなく、公開されている JSON から値を取り出して表示することもできます。
例えば、API が次の JSON を返すとします。
{
"name": "my-web-app",
"version": "2.4.1",
"tests": {
"coverage": 92
}
}
カバレッジの値だけを取り出す場合は、JSONPath を query に指定します。
https://img.shields.io/badge/dynamic/json?url=YOUR_ENCODED_JSON_URL&query=%24.tests.coverage&label=coverage&suffix=%25&color=green
ここで指定している内容は次のとおりです。
url：公開 JSON の URL（URL エンコードして指定）query=%24.tests.coverage：JSONPath の$.tests.coveragelabel=coverage：左側のラベルsuffix=%25：値の末尾に%を付けるcolor=green：背景色
実際に使う際は YOUR_ENCODED_JSON_URL をアクセス可能な URL に置き換えます。
参考：Dynamic JSON Badge の公式ドキュメント
なお、JSON は Shields.io のサーバーから取得できる必要があります。localhost や社内ネットワークでしか参照できない API は、そのままでは利用できません。
8. 独自のデータを渡す：Endpoint Badge
バッジのラベルや色などを API 側でまとめて制御したい場合は、Endpoint Badge が便利です。
例えば、次のような JSON を返すエンドポイントを用意します。
{
"schemaVersion": 1,
"label": "deployment",
"message": "production",
"color": "brightgreen"
}
公開 URL が次のようになっているとします。
https://example.com/api/badge.json
バッジの URL は次のように指定できます。
https://img.shields.io/endpoint?url=https%3A%2F%2Fexample.com%2Fapi%2Fbadge.json
この場合、表示内容は API が返す JSON によって決まります。
| 種類 | 用途 |
|---|---|
| Static Badge | 固定の文字列を表示する |
| Dynamic JSON Badge | 既存の JSON API から特定の値を抽出する |
| Endpoint Badge | API 側でラベル、値、色などをまとめて定義する |
Endpoint Badge では labelColor や namedLogo、logoSvg などのオプションも利用できます。詳細は公式ドキュメントを参照してください。
9. 実例：自分の GitHub Profile 用の技術スタック
自分の README に入れるなら、技術を一行にすべて並べるより、フロントエンド・バックエンド・データベース・開発ツールに分けた方が読みやすいと思います。
以下はそのまま Markdown に貼り付けられるサンプルです。
Frontend
Backend
Database & ORM
DevOps & Tools
この形式なら、使用する技術が増えたときも分類ごとに追加できます。ただし、バッジはあくまでも表示用なので、経験年数や習熟度まで示してくれるものではありません。
10. よくある問題と注意点
バッジが表示されない
まずは Markdown から画像 URL を取り出し、ブラウザで直接開いてみます。
その上で、次の点を確認すると原因を絞りやすいです。
logoに指定した Simple Icons の slug が正しいか- 空白、ハイフン、
%などが適切にエスケープされているか - 動的バッジの場合、リポジトリや JSON の URL が存在し、外部からアクセスできるか
- ブログ側で外部 SVG の読み込みが禁止されていないか（CSP や画像プロキシの設定など）
エディターのプレビューと実際のブログ画面では、表示結果が違う場合もあります。公開ページでも一度確認した方がよいです。
バッジをクリックできるようにしたい
Markdown の画像だけではリンクになりません。次のように画像をリンクで囲みます。
[](https://vuejs.org/)
動的バッジはリアルタイムで更新される？
必ずしもリアルタイムではありません。Shields.io や参照先サービスでキャッシュされることがあり、変更が反映されるまで時間がかかる場合があります。cacheSeconds を指定しても、常に指定どおりの間隔で更新されるとは限りません。
個人ブログにも使える？
外部 SVG 画像の埋め込みに対応しているブログなら利用できます。通常は Markdown の画像構文だけで十分です。外部画像が制限される場合は SVG を保存して配置する方法もありますが、その場合は動的更新ができなくなります。
本番環境の監視に使ってもよい？
README に状態を表示する用途には便利ですが、障害検知やアラート、ログ監視、APM などの代わりにはなりません。本番運用では専用の監視サービスを使用するべきです。
11. まとめ
Shields.io の便利なところは、画像ファイルを自分で作成・管理せずに、URL だけでバッジを表示できることです。
個人の GitHub Profile なら技術スタックを静的バッジでまとめ、公開リポジトリなら npm のバージョンや GitHub Actions の実行結果などを動的バッジで表示する、といった使い分けができます。
ただ、README はバッジを大量に貼れば見やすくなるわけではありません。スタイルを揃えて必要な情報に絞る方が、結果的に読みやすくなります。
最終的にプロジェクトの価値を伝えるのは、バッジの数ではなく、コードやドキュメント、そしてどんな問題を解決しているかだと思います。