プルリクエストでよく使う丁寧な証跡のためのマークダウンとHTML

## はじめに

GitHubでPull Requestを提出する際にエビデンス（証跡）を丁寧に記載することはレビュワーの負荷を軽減するでしょう。

今回は、マークダウン・HTMLを中心にエビデンスに使える書き方を紹介します。

# 基本

## 画像

画像はそのまま添付するとサイズが大きくなりがちです。
そのため、`<image>`タグで記載してあげると丁寧です。

```md
<img src="{画像URL}" width="300px" >
```

画像URLは画像をPull Requestの概要エリアにドラッグ＆ドロップなどすれば表示されます。

### サンプル
```md
## そのまま

![kurogoma-w](https://github.com/user-attachments/assets/982601fc-6f3b-407b-a8b0-4a7f9b00a3af)

## imageタグ
<img src="https://github.com/user-attachments/assets/982601fc-6f3b-407b-a8b0-4a7f9b00a3af" width="200px" >
```

![スクリーンショット 2024-12-16 22.43.31.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/735195/9e903212-0bba-5578-94d0-74795c0ba520.png)


## 動画

動画も画像同様`<video>`タグで表示すると丁寧でしょう。
注意点として、`<vide>`タグは閉じタグを必要とします。閉じタグを忘れた場合それより下に書いた記述が見えなくなってしまいます。

```md
<video src="{動画URL}" width="300px"></video>
```

# 複数表示する場合

## マークダウンのtable

`/table`と入力するとテーブルビューを自動で記載することができます。
先ほどのimageタグと組み合わせても良いでしょう。
（複数入力する場合無理にimageタグを使わなくても大丈夫です）

```md
| 結果1 | 結果2 | 結果3 |
|--------|--------|--------|
| <image src="" > | <image src="" > | <video src="" ></video> | 
```

## HTMLのテーブル

マークダウンで書く場合、URLが長くなると区切りがわかりにくくなるためHTMLで書いた方がわかりやすい場合もあります。

```md
<table>
  <thead>
    <tr>
      <th>結果1</th>
      <th>結果2</th>
      <th>結果3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><img src="" alt="結果1画像"></td>
      <td><img src="" alt="結果2画像"></td>
      <td><video src=""></video></td>
    </tr>
  </tbody>
</table>
```

しかし、この程度であればどちらで書いても結果は同じです。

### サンプル

```md

## マークダウン

| 結果1 | 結果2 | 結果3 |
|--------|--------|--------|
| <image src="" alt="結果1画像" > | <image src=""  alt="結果2画像" > | <video src="" ></video> | 

## HTML

<table>
  <thead>
    <tr>
      <th>結果1</th>
      <th>結果2</th>
      <th>結果3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><img src="" alt="結果1画像"></td>
      <td><img src="" alt="結果2画像"></td>
      <td><video src=""></video></td>
    </tr>
  </tbody>
</table>
```

![スクリーンショット 2024-12-16 22.52.21.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/735195/15db2c22-58e1-e485-43f3-e0ac5e4268ab.png)


## Before Afterの比較

先ほどのテーブルビューを用いればBEFORE / AFTERの記載も簡単になります。

## BEFORE/AFTER 単体（マークダウン）

```md
| BEFORE | AFTER |
|--------|--------|
| <img src="" alt="before画像"> | <img src="" alt="after画像"> | 
```

## BEFORE/AFTER 単体（HTML）

```md
<table>
  <thead>
    <tr>
      <th>BEFORE</th>
      <th>AFTER</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><img src="" alt="before画像"></td>
      <td><img src="" alt="after画像"></td>
    </tr>
  </tbody>
</table>
```

## BEFORE/AFTER（複数）

次に、2つずつBefore/Afterを記載したい場合の書き方です。
テーブルを結合して記載します。

テーブル結合はGitHubのマークダウンでサポートされてないため、直接HTMLで記載しましょう。

```md
<table>
  <tr>
    <th colspan="4">エビデンス</th>
  </tr>
  <tr>
    <th colspan="2">Before</th>
    <th colspan="2">After</th>
  </tr>
  <tr>
    <td><img src="image_before_1.png" alt="Before Image 1"></td>
    <td><img src="image_before_2.png" alt="Before Image 2"></td>
    <td><img src="image_after_1.png" alt="After Image 1"></td>
    <td><img src="image_after_2.png" alt="After Image 2"></td>
  </tr>
</table>
```

![スクリーンショット 2024-12-16 23.03.43.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/735195/31ca8804-4710-ee61-6666-bd988162b301.png)

## その他小ネタ

### 折りたたみUI

```md
<details>
<summary>詳細を見る</summary>

ここに詳細な説明や提案、長いログを記述
</details>
```
![スクリーンショット 2024-12-16 23.16.31.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/735195/405ece2f-59e6-dea2-c029-8d6b508cf387.png)

### アラート記法

`/alerts`と入力すると候補が出てきます

```md
> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.
```

![スクリーンショット 2024-12-16 23.18.23.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/735195/0ccea374-23aa-47ca-d4cb-2422087935c0.png)

### 注釈

あまりPRで使うものではないのでしょうが、ブログなどである注釈機能も使えます

```md
Here is a simple footnote[^1].

A footnote can also have multiple lines[^2].

[^1]: My reference.
[^2]: To add line breaks within a footnote, prefix new lines with 2 spaces.
  This is a second line.
```

### マークダウンを打ち消す（エスケープ）

勝手にマークダウンになって欲しくない場面もあると思います。
その場合は`\`を用いましょう。

```md
普通は**太字**になってしまう

これは\**太字\**にならない
```

![スクリーンショット 2024-12-16 23.24.21.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/735195/32ea4212-6d93-5b6a-bdbb-0903683cc1cd.png)

### 内部リンク

同じPR内でリンクを貼りたい場合以下のようにできます

```md
# Link
- [README](#README)
- [使い方](#使い方)

## README

README

## 使い方

使い方
```

![スクリーンショット 2024-12-16 23.32.04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/735195/28f453fc-2ee0-272a-10d5-4f1803754edf.png)

:::note warn
注意
:::

しかし、このリンクは若干厄介です。
書き方に注意が必要なためうまくいかない場合は以下の記事を参考にしてみてください。

https://qiita.com/hennin/items/7ee58dd7d7c013a23be7

## 公式ドキュメント

https://gist.github.com/uupaa/6061529