バッジ on README.md
OSSをGitHub等で公開するにあたっては、様々な情報をバッジとしてREADME.mdに貼っておくことがよくあると思います。
クラウドサービスを活用して README にバッジをペタペタ貼る - Qiita
（画像引用）
私もバッジは貼りたい派です。
- シャレている
- テスト、ビルド結果を表示しておくというのが恐らく最も主要な目的であり（要出典）、必然的に：
- テストの存在、
- （テストを整備、維持しようとする気持ち、）
- 自動テストand/orビルド環境の存在、などを前提とする
- README.mdを小綺麗に整えようという姿勢を示せる
- カラフルでシャレている
正直、目的意識についてはあえてあまり深く考えない方がいいしてきた。
とりあえず貼っていこう。
動的な情報をバッジとして表示する
masterのテスト結果やcode climateなどは、その情報を握っているwebサービス自体がSVG等の画像を動的生成するAPIを持っていることが多く、そのURLを画像のソースURLとして直接指定することで簡単にバッジとして表示できます。
また、ユーザ指定の静的な情報をバッジとして表示するのも、shields.ioを使うことで簡単にできます。
https://img.shields.io/badge/<SUBJECT>-<STATUS>-<COLOR>.svg
このような形式のURLを用意するだけ。
https://img.shields.io/badge/sample-good-green.svg
こう書けば、
こうなります。日本語もいけるようです。
では、webサービスに関連付いたものでもない（shields.ioにもバッジが用意されていない）が、かといって静的なものでもなく、どこかに保存されていて動的に変化しうる情報をもとにバッジを表示したい場合はどうするのがいいでしょうか。
実はこれもshields.ioでできます。条件は、
- 元情報がJSONで取れて、
- 認証が不要であること。
たとえば、Elmのpackageは http://package.elm-lang.org に集約されていますが、shields.ioにはまだelm-package versionバッジは用意されていません。RubyGemsやnpmのようにそのうち対応するのを待ってもいいですし、ない間は手書きで書いておくという手もありますが、そこはやっぱり自動生成させましょう。
shields.ioにはdynamic badgeという機能があります。以下のようにURLを構成して画像ソースに指定するだけ。
/badge/dynamic/<TYPE>.svg?uri=<URI>&label=<LABEL>&query=<$.DATA.SUBDATA>&colorB=<COLOR>&prefix=<PREFIX>&suffix=<SUFFIX>
| slot | value |
|---|---|
TYPE |
今のところjsonだけの模様 |
URI |
情報取得元のURL。URL encodeしましょう。認証不要で、JSONを返すならなんでもOKのはず |
LABEL |
バッジの左半分に表示するラベル |
$.DATA.SUBDATA |
取得したJSONのどこのフィールドの値をバッジの右半分に表示するか。JSONPathクエリで指定 |
COLOR |
バッジ右半分のHex color |
PREFIX |
クエリで取得した文字列につける接頭辞 |
SUFFIX |
同じく接尾辞 |
Elm packageの最新バージョンは、GitHubレポジトリのmasterにある、elm-package.jsonというファイルのversionフィールドの値を正とすればいいでしょう。raw.githubusercontent.comから取ってこれますね。
- （GitHubにはpushしてあるが
elm-package publishはしていない、という状態もあり得ますが、気にしません） - （ちなみに、Elm 0.19以降は
elm.jsonとなります）
組み合わせて、
https://img.shields.io/badge/dynamic/json.svg?label=elm-package&colorB=5f9ea0&query=$.version&uri=https%3A%2F%2Fraw.githubusercontent.com%2Fymtszw%2Felm-xml-decode%2Fmaster%2Felm-package.json&prefix=v
このURLにより、
このように生成できました。
おわり
書いといてなんですが、badgeは表示先サービス（ここではGitHub,それにQiita）の画像cacheとの兼ね合いで、表示されないことが時々あります。1
そこへ来て元情報まで外部リソースに依存するdynamic badgeともなると、さらに失敗する確率は上がります。
shields.ioのサーバが反応しないケースもありえます（rate limitか過負荷なのかは不明）。
実はこの記事の例もタイミングによって表示されてないケースが結構あったので、こっそりPNGに逃げています！ あしからず。
static badgeの方が多少はマシだと思うので、バージョン番号表示くらいならstaticにしてversion upのたびに書き直しが無難かも。
適切に使い分けつつ、なんでもバッジ表示してシャレオツにしていきましょう。
-
shields.io側に
?maxAge=3600などのオプションもあるので、ある程度コントロールできそうです。 ↩