Shields.io を使ってバッジを表示する

### はじめに

Githubとかでよく見る↓のような小さいバッジ。
作り方を調べては忘れてを繰り返しており、定着しないので自分なりに整理してみます。

![Github](https://img.shields.io/badge/Github-MyAccount-red.png?logo=github&logoColor=white)

![Kotlin](https://img.shields.io/badge/-Kotlin-7F52FF.png?logo=kotlin&logoColor=white)

情報元は下記の公式ページです。

https://shields.io/badges


### 基本形: パスパラメータのみ使用

ロゴなしの基本的な形はパスパラメータの指定のみで作れます

![basic](https://img.shields.io/badge/simple-badge-blue) - ```https://img.shields.io/badge/simple-badge-blue```


#### パスパラメータの説明

下記の通り、`label`、`message`、`color`をダッシュ（`-`）区切りで指定します。
バッジの左部分が`label`で右部分が`message`です。

```
label-message-color
```

`label`と`message`は両方が必須なのではなく、片方だけの指定でも構いません。

![basic](https://img.shields.io/badge/MessageOnly-yellow) - ```https://img.shields.io/badge/MessageOnly-yellow```

色の指定には、色の名称やカラーコードなどが使えます。
なお、ラベルとメッセージの両方がある場合には`color`ではメッセージの色が設定されます。ラベルの色指定には、後述するクエリパラメータの`labelColor`を使ってください。

![basic](https://img.shields.io/badge/simple-badge-3E72BC) - ```https://img.shields.io/badge/simple-badge-3E72BC```

![basic](https://img.shields.io/badge/simple-badge-rgb(106,90,205)) - ```https://img.shields.io/badge/simple-badge-rgb(106,90,205)```

##### エラー

前述のパスパラメータの条件を満たしていないなど、不適切なURL指定をすると`404`が返ってきて下記のように表示されます。

![basic](https://img.shields.io/badge/invalid) - ```https://img.shields.io/badge/invalid```

#### 拡張子

URL末尾が画像の拡張子で終わっていれば、画像として解釈されます。
と言っても、私が試してみて使えたのは`png`と`svg`だけでした。

![png](https://img.shields.io/badge/This_is-png-3E72BC.png) - ```https://img.shields.io/badge/This_is-png-3E72BC.png```

![svg](https://img.shields.io/badge/This_is-svg-B33013.svg) - ```https://img.shields.io/badge/This_is-svg-3E72BC.svg```

`gif`や`jpg`を使おうとすると`410`が返ってきます。

![gif](https://img.shields.io/badge/This_is-gif-3E72BC.gif) - ```https://img.shields.io/badge/This_is-gif-3E72BC.gif```

![jpg](https://img.shields.io/badge/This_is-jpg-3E72BC.jpg) - ```https://img.shields.io/badge/This_is-jpg-3E72BC.jpg```

それ以外の、`bmp`や`tiff`に至っては`404`になってしまいました。

![bmp](https://img.shields.io/badge/This_is-gif-3E72BC.bmp) - ```https://img.shields.io/badge/This_is-gif-3E72BC.bmp```

![bmp](https://img.shields.io/badge/This_is-gif-3E72BC.tiff) - ```https://img.shields.io/badge/This_is-gif-3E72BC.tiff```

なお、拡張子を何も付けなければ、デフォルトで`.svg`になるようです。


### 発展形: クエリパラメータを使用

より細かい設定のためにはクエリパラメータを使用します。ロゴもクエリパラメータで指定します。
様々なパラメータが用意されていますが、よく使いそうなものをいくつか解説します。

ちなみに私が確認できている限りでは文字色を指定する方法はありません。背景色に応じた色が文字色として使用されるようです。

#### logo

バッジにロゴを表示できます。
基本的には`Simple Icons`のロゴが使えますが、Shields自身が保守しているロゴもいくつかあるようです。

https://simpleicons.org/

https://github.com/badges/shields/tree/master/logo

![Tomcat](https://img.shields.io/badge/Tomcat-grey.png?logo=apachetomcat) - ```https://img.shields.io/badge/Tomcat-grey?logo=apachetomcat```

![Gitlab](https://img.shields.io/badge/Gitlab-white.png?logo=gitlab) - ```https://img.shields.io/badge/Gitlab-white?logo=gitlab```

ロゴの名前（Tomcatの場合は`apachetomcat`）は、Simple Iconsでロゴのタイトルをクリックするとクリップボードにコピーされます。
あるいはSimple Iconsのリポジトリにある[slugs.md](https://github.com/simple-icons/simple-icons/blob/master/slugs.md)からも探せます。

用意されているものではない、任意のカスタムロゴを使用する場合、base64エンコードした値を使用します。詳細は公式ページで確認してください。

https://shields.io/docs/logos

###### logoColor

ロゴ部分の色を指定します。
下記の例では、`logoColor=red`によりGithubのロゴを赤くしています。

![logoColor](https://img.shields.io/badge/Github-MyAccount-white.png?logo=github&logoColor=red) - ```https://img.shields.io/badge/Github-MyAccount-white?logo=github&logoColor=red```

###### labelColor

ラベル（バッジの左部分）の背景色を指定します。
下記の例では、`labelColor=yellow`により、左側の背景色を黄色にしています。

![labelColor](https://img.shields.io/badge/label-message-white?labelColor=yellow) - ```https://img.shields.io/badge/label-message-white?labelColor=yellow```

###### color

バッジの右部分の背景色を指定します。
こちらがパスパラメータよりも優先されます。
下記の例ではパスパラメータで`red`、クエリパラメータで`blue`を指定したところ、右側の背景色が紫になっています。

![color](https://img.shields.io/badge/label-message-red?color=purple) - ```https://img.shields.io/badge/label-message-red?color=purple```

#### style

バッジの見た目を指定します。指定しない場合のデフォルトは`flat`です。

| style | sample |
|--|--|
| flat | <img alt="flat" src="https://img.shields.io/badge/this_is-sample-white?style=flat" /> |
| flat-square | <img alt="flat-square" src="https://img.shields.io/badge/this_is-sample-white?style=flat-square" /> |
| plastic | <img alt="plastic" src="https://img.shields.io/badge/this_is-sample-white?style=plastic" /> |
| for-the-badge | <img alt="for-the-badge" src="https://img.shields.io/badge/this_is-sample-white?style=for-the-badge" /> |
| social | <img alt="social" src="https://img.shields.io/badge/this_is-sample-white?style=social" /> |

### Webページでの表示

画像のソースとして Shields.io のURLを入力することで表示できます

HTML

```html
<img alt="badge" src="Shields.ioのURL" />
```

Markdown

```md
![badge](Shields.ioのURL)
```

例として、下記のバッジを表示する場合を記載しておきます。

![logoColor](https://img.shields.io/badge/Github-MyAccount-white.svg?logo=github&logoColor=red)

HTML

```html
<img alt="Github" src="https://img.shields.io/badge/Github-MyAccount-white?logo=github&logoColor=red" />
```

Markdown

```md
![Github](https://img.shields.io/badge/Github-MyAccount-white?logo=github&logoColor=red)
```

### 特殊文字

スペース（` `）などURLにそのまま入力できない文字や、ダッシュ（`-`）のようにShields.ioにおいて意味を持つ文字を出力したい場合には、下記のように置き換えます。

| URLへの入力 | バッジへの出力 |
|-----------|--------------|
| アンダースコア(`_`) | スペース（` `） |
| ダブルアンダースコア(`__`) | アンダースコア（`_`） |
| ダブルダッシュ(`--`) | ダッシュ（`-`） |

![space](https://img.shields.io/badge/any_text__-you--like-blue) - ```https://img.shields.io/badge/any_text__-you--like-blue```

URLエンコードされたASCII文字も使えるので、スペースは上記のアンダースコアでなく`%20`も使えますし、`C#`のバッジなどで使いそうなシャープ（`#`）も`%23`が使えます。

![C#](https://img.shields.io/badge/C%23-512BD4.png?logo=csharp) - ```https://img.shields.io/badge/C%23-512BD4?logo=csharp```

詳細は下記のページを確認してください。

https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding