Zenn
🏸

おしゃれなREADME.mdを作って「このプロダクト凄そう..!(?)」と勘違いさせたいあなたへ

2022/05/16に公開2件
Git
GitHub
#
OSS
#
readme
tech

はじめに

ひどいREADMEを量産してるので、ここらでオシャレREADMEを作ろうと決意しました。
その備忘録です。

hidoi-readme

注意点

※ 今回は見た目いい感じにするに振り切っています。もちらん大事なのは使い方、仕様をしっかり書くことです。。
でも見た目がいい感じだと、その他も頑張って書こうという気持ちになったので、結果いいREADMEに繋がるのではと思っています。

さあ、作るぞ！

といってもどうすればいい感じになるのか？ その謎を解明するため、我々はGitHubの奥地へと向かったーー。

README訪ね歩き

slidev

まず見たのはこちら。プレゼンスライドをmarkdownからいい感じに作ってくれるライブラリらしい。
Slidev

READMEがこちら。
Slidev README

あらオシャレ😍

更には、、

Slidev README2

す、スポンサー、、しかもすごい数、、、
イケてるライブラリ感がすごいぞ...!!

reviewdog

お次はこちら。linterの指摘を自動でプルリクのメッセージに表示してくれるらしい。
reviewdog

READMEはこちら。

reviewdog README

ものすごい数のバッジ(?)が並んでいる...!!良くわからないが、これだけですごそうだ。

分かったこと

ということで、どうやらイケてるREADMEにするためには、

  1. いい感じのロゴを載っける
  2. バッジを並べる

という作戦が有効そうだと分かった。
(僕のプロダクトでは大層悲しいことになりそうなので、スポンサーやらコントリビュータのアイコンを並べるのは採用を見送る。いつか凄いの作ったら採用してやるからな)

やることさえ決まってしまえばこっちのもんよ。

いい感じのアイコン作成

といっても、我々はデザインに関してはズブの素人。いきなり躓いてしまう。
おしゃれなロゴをパクってしまおうかと血迷った矢先に、こんなサービスが目に飛び込んできた。

hatchful
なんと、無料でオシャレアイコンを作成してくれるし、商用利用もOKとのこと。
試しにnice READMEというロゴを作ってみるべく、画面をポチポチすること数回。。

osyare-icon
僕が逆立ちしてもできないようなおしゃれアイコンの数々が星の数ほど出てくる。。これが無料とは。。。
適当なやつをダウンロード。ロゴ問題はOKそう。

バッジを並べる

続いてはイケてそうなバッジをたくさん並べるのを試みた

まずは

reviewdogをモデルとして、どんなバッジを武装しているのか紐解いてみる。
しょっぱなはこちら！
licence

MIT licence なだけかい。笑

次！

release

リリースノートへのリンク。。まあ確かに。。。

次！

cicd

CI/CD系をちゃんと通っているかのバッジ達。
Github actions, Travis, Circle CIと3箇所でやってるのか、、
バッジの数を稼げて良いかもなあ(違)

次！

coverage

テストのカバレッジ。なるほど。これは確かに。

ラスト！

star

..恐れ入りました

ということで

勝手に身構えていたが、思っていたより当たり前無難な内容でバッジが載せられそうと分かった。
他にもバッジをたくさん載っけてくれているリポジトリや文字、色を指定するとバッジを返してくれるサービス(shields.io)なんてのもあるらしい。

AWSやReact, 果てはyarnとかでもバッジがあるので、もう何でもやりたい放題の様相みたいだ。
バッジの埋め尽くし方は自らの倫理観と相談する必要がありそう。

気に入ったバッジ

あたりまえ体操のバッジ群とは異なり、あっても良いなあと思ったのがいくつかあったので紹介する。

Open in VScode

vscode
こちら、押すとブラウザ版のVScodeで該当リポジトリのコードを見れるバッジである。

導入の仕方は簡単、以下についてパスの末尾を修正した上でREADME.mdに書き込むだけである。

[![Open in Visual Studio Code](https://img.shields.io/static/v1?logo=visualstudiocode&label=&message=Open%20in%20Visual%20Studio%20Code&labelColor=2c2c32&color=007acc&logoColor=007acc)](https://open.vscode.dev/｛GitHubのuser名｝/{リポジトリ名})

github actions

GitHub actionsのCI/CDが通過しているかを載せられるバッジ。

こちらも導入は簡単、先程同様パスを修正するだけである。

![workflow](https://github.com/｛GitHubのuser名｝/{リポジトリ名}/actions/workflows/{workflowのyamlファイル名}/badge.svg)

jest coverage

jestによるテストについて、カバレッジを載せられるバッジ。

こちらはjest-coverage-badgesというライブラリを使ってバッジを生成する。
導入方法は以下の通り

  1. jest-coverage-badgesをインストール
    $ npm install --save jest-coverage-badges
  2. package.jsonを編集
    "jest": {
  "coverageReporters": [
    "json-summary", 
    "text",
    "lcov"
  ]
}
...
"scripts": {
  "test:coverage": "npm test -- --coverage",
 "test:badges": "npm run test:coverage  && jest-coverage-badges"
}
  3. jest-coverage-badgesを実行
    $ npm run test:badges
  4. バッジが生成
    • ./coverage/badge-statements.svg
    • ./coverage/badge-lines.svg
    • ./coverage/badge-functions.svg
    • ./coverage/badge-branches.svg

もちろん、github actionsなどのCIツールで動かせば、勝手にバッジを更新してくれる。
coverageディレクトリを.gitignoreしないようご注意を

最後に

ここまで読んだあなたは、すぐにおしゃれREADMEを作成できるはずです。
ややめんどくさいのは否めませんが、冒頭にも書いたとおり

「最初だけ見栄えいいのも変だから、残りもちゃんとREADME書くぞ！」

という気持ちが芽生えてくるので、キューソネコカミタイプのあなたにおすすめです。

他にも手っ取り早くREADMEをいい感じにしてくれる方法があれば教えて下さい。
皆様のアイデアお待ちしています。

私も初めて頑張ってREADME書いてみたOSSがこちらです。
ぜひ眺めてやって、気に入ったら使ってみてください。
（いいねボタンのバックエンドサーバを提供します）

Liketion

Discussion