この記事は 夏のブログリレー 18日目です。

はじめに

みなさんは Markdown を使ったことがありますか？？

Markdown は整った文書を記述するための言語で、その記法はかなり分かりやすいものになっています。
Markdown は主にブログ等の記事を書く際や、GitHubでドキュメントを記述するとき、さらにDiscordなどのチャットツールでメッセージを装飾するのに用いることができます。
また、traP の内製チャットツールである traQ でも、メッセージを Markdown で装飾することができます。

このように今では広く普及している Markdown 言語ですが、私は最近「キレイさ」を意識して Markdown を書くように心がけているので、この記事ではそれについて少し紹介しようと思います。

キレイな Markdown とは？

ここで言っている「キレイな」とは、「ソースコードの状態でも読みやすい」ということです。

Markdown ではスペースや空白行が無くてもほとんどの場合は良いのですが、私はソースコードの見やすさを考えてあえてそれらを入れることが多いです。

心がけていること

1. 積極的に空白行で区切る

空白行で区切る必要が無いものとして、主に以下のものが挙げられます。

• 見出し (前後とも不要)
• コードブロック (前後とも不要)
• 引用 (後に普通の文章が続く場合のみ, ブロックの直後に必要)
• リスト (要素が空白である場合は直前に必要 / 後に普通の文章が続く場合はブロックの直後に必要)

そのため、以下のように記述しても問題ありません。

# 見出し
本文
本文
> 引用
> 引用
```cs
Console.WriteLine("Hello World!");
```
- リスト要素(1)
    - リスト要素(2)

しかし、上の例は少し見づらいと感じませんか？？

では、ブロックを空白行で区切って以下のようにしてみるとどうでしょうか。

# 見出し

本文
本文

> 引用
> 引用

```cs
Console.WriteLine("Hello World!");
```

- リスト要素(1)
    - リスト要素(2)

こちらのほうがブロックごとにまとまっていて見やすく感じると思います。

そのため、私は積極的に空白行を入れるように心がけています。

2. 見出しは階層を意識する

見出しは # を1~6個重ねて階層のレベルを指定しますが、以下の例のようにレベル2の次にレベル4の見出しを指定してしまうと、混乱を招いてしまうことがあります。

## 今日のごはん

#### 朝食

- ごはん
- 味噌汁
- 納豆

こうならないように、見出しのレベルを深くする際は、下の例のように1つずつ変化させるようにしています。

## 今日のごはん

### 朝食

- ごはん
- 味噌汁
- 納豆

3. リンクやコードの前後にスペースを入れる

細かいようですが、これは出力後の見た目にも影響するので、出力後の見やすさも意識して前後にスペースを入れるようにしています。

文章中に `コード` や [リンク](https://trap.jp) を挿入します。

試しに前後にスペースがないコードと 前後にスペースがあるコード を並べてみたり、
前後にスペースがないリンクと 前後にスペースがあるリンク を並べてみると、意外と違って見えるんじゃないでしょうか。

4. リンクは明示する

多くの場合、URLをそのまま打つだけで自動的にリンクが張られますが、URLを <> で囲むことで自動でリンクを張ることを明示します。

<https://trap.jp>

参考にしているサイト

実は、これまで述べてきたものはだいたい Basic Syntax | Markdown Guide に書かれていて、私もこれを参考にしながら Markdown を書いています。

このサイトでは Markdown の文法に加えてベストプラクティスも紹介されており、良い例と悪い例が記載されていて分りやすいです。

役に立つ VSCode 拡張機能

私は VSCode に markdownlint を導入して使っています。

これは Markdown のコードの不備や改善点を指摘してくれるので、かなり役に立っています。
皆さんもぜひ導入してみてください。

終わりに

いかがでしたか？
Markdown を書く際は、ぜひこの記事の内容を思い出してみてください！

明日は @d_etteiu8383 さん、 @vPhos さんの記事です！
楽しみ～