フロントエンドエンジニアのかまねこです。Neulabには入社して7年目になります。リンク先のZennのアカウントは作成したのですがさっぱり記事は書いておらずです。
これまで技術ブログの記事は私が一人で書いていましたが、今後は他の開発メンバーにも記事を書いてもらう予定です。どんな人が書いた記事なのかがわかりやすいように、今回から冒頭に簡単な自己紹介を載せていきます。
はじめに
READMEとは、新しくプロジェクトに関わる人がスムーズに取り掛かれるようにプロジェクトの概要や環境構築手順、使用しているバージョンなどを書いておくファイルです。 読みやすいREADMEにするためにバッジを取り入れるのが良いと感じたので紹介します。 世の中に公開されているサービスやライブラリのREADMEにはShields.ioで作成したバッジがよく付いています。 例えば今回紹介するShields.ioのREADMEはこのようにバッジが付いています。
文字情報のみよりグラフィカルな方が見やすいですね。Shields.ioを使えば見た目を整えるだけでなく情報更新等のメンテナンスを楽にすることが可能です。作成の仕方を見てみましょう。
Shields.ioとは
Shields.ioはREADMEやWebページに埋め込めるSVG形式のバッジを簡単に作成、表示できる無料サービスです。作成したバッジはダウンロードなどの必要なく、URLを指定するだけで表示させることができます。
バッジの作り方
Staticバッジ
まずは基本的なStaticバッジの作り方です。https://img.shields.io/badge/の後ろに「ラベル-メッセージ-メッセージの背景色」をハイフン区切りで指定すればOKです。
例えば、https://img.shields.io/badge/label-message-blueこのようなラベルを作ると見た目はこのようになります。
これが基本の形で他に変更したいパラメータがある場合はクエリパラメータで指定します。例えばバッジのスタイルをfor-the-badge、ラベルの背景色を黒にしたい場合はこのように指定します。
https://img.shields.io/badge/label-message-blue?style=for-the-badge&labelColor=black
出来上がるバッジはこのようになります。
ロゴをバッジ内に表示させることもできます。表示できるロゴはsimple-iconsで提供されているロゴが使用できます。 例えばNode.jsのアイコンを含んだバッジを作成したいならsimple-iconsでnodeと検索します。アイコンを見つけたら名称の部分をクリックしてスラッグをコピーしましょう。
クエリパラメータでlogo=の後ろにコピーしたスラッグを入れれば完了です。
ラベルとメッセージを変えてこうすればプロジェクトで使用しているNode.jsのバージョンがわかりやすいですね。
Dynamicバッジ
Staticバッジではバージョン情報などの変更があった際に書き直す必要があります。もちろんこまめにREADMEをアップデートするのは必要なことですが、できれば自動で情報を取ってきて表示する形式にしたいですよね。Shields.ioにはDynamicバッジというバッジ作成方法もあります。今回はその中でDynamic JSONバッジの作成の仕方を見てみましょう。
こちらの公式ページに作成方法が載っています。右側にジェネレーターがあるので使ってバッジを作成してみましょう。
urlにJSONを返すURLを指定します。これは公開リポジトリならpackage.jsonのファイルでもいいですし何か別のJSONを返却してくるAPIのURLでも良いです。例にあるようにShields.ioのpackage.jsonを指定してみます。 queryに表示したいJSONのkeyを入れます。バージョンを表示してみたいので$.versionを入れましょう。
下のExecuteボタンを押してバッジの見た目を確認してみましょう。package.json内のversionの値がバッジに表示されたのが確認できます。
これでDynamicバッジを作成できました。あとはURLやMarkdownなど好きな形式をコピーして使用箇所に貼りましょう。
jsonの値が変化すればバッジに表示される値も自動で変わってくれます。
ジェネレーターの「+ Show optional parameters」部分をクリックすればラベルの文字や色などの変更も可能です。
GitHub Actions
GitHub Actionsの実行結果をバッジで載せることもできます。 これはGitHubがshieldsを使って提供してくれている機能です。GitHub Actionsのページでバッジにしたいワークフローを選択し、右上のボタンから「Create status badge」を選びます。
バッジの見た目と表示するためのマークダウンが出ます。下のボタンからマークダウンをコピーしてREADME.mdにペーストすれば完了です。
この機能はリポジトリがプライベートでもGitHub内なら問題なくバッジの表示ができるようです。
Neulabで使用しているサービスではQltyも同様にバッジ機能を提供していました。探してみると、他にもバッジ提供しているサービスが見つかると思います。
おわりに
Shields.ioを使えば、READMEに「ひと目で伝わる情報」を簡単に追加できます。 Staticバッジで見た目を整えるのも良いですし、Dynamicバッジを使えばメンテナンスコストを抑えながら常に最新の情報を表示できます。
READMEはプロジェクトの最初の入口になる場所なので、ちょっとした工夫で印象や分かりやすさが大きく変わります。 まだバッジを使ったことがない方は、まずはバージョン情報やCIのステータスなど、取り入れやすいところから試してみてください。
今後もNeulabの開発メンバーそれぞれの視点で技術記事を発信していく予定なので、ぜひ他の記事も読んでもらえるとうれしいです。
