ここ数年、開発資料などを Markdown 形式で執筆することが多くなってきました。ブログサイトなども Markdown 原稿を SSR・SSG して公開する例も増えています。
自分も6・7年ほど Markdown 形式と戯れてきましたが、分かりやすい Markdown 文書を書くためにはいくつか押さえておかないといけないポイント、テクニック、マインドがあると感じています。
今回は自分の経験から、このように書くと分かりやすくなる、と思うポイントを紹介します。どちらかというと Markdown の構文を基にしたポイントを記しており、例えば textlint で指摘されるような文章校正の観点は含んでおりません。
全体的なポイント
Markdown という形式全般に対していえることです。
- Markdown はプレーンテキストでも読みやすい形式として生み出されたものです。よって、プレーンテキストでも読みやすく書くことが、最終的な可読性にも繋がります
- プレーンテキストでも読みやすく構文を統一して書いていると、「ググラビリティ」も向上します。すなわち、複数の Markdown ファイルを横断的に
grepする際に、正規表現で絞り込みやすくなるのです
- プレーンテキストでも読みやすく構文を統一して書いていると、「ググラビリティ」も向上します。すなわち、複数の Markdown ファイルを横断的に
- Markdown は歴史的な経緯により、「パーサ」の仕様が一つに定まっていません。CommonMark や GitHub Flavored Markdown の仕様に準拠する流れが一般的なので、それらに従っておくと、どこに持ち込んでも正しくパースされる、可搬性の高い Markdown ファイルになるでしょう
- Markdown は最終的に HTML にパースされることを意識しましょう。Markdown 内で見栄えを制御しようとしないでください。そうではなく、パース後の HTML に CSS を当てて対処する方が綺麗でしょう
- 読みやすい Markdown 文書とは、読みやすい HTML 文書でもあると思います
見出し (h1 〜 h6 要素)
# 見出し1
## 見出し2
本文
### 見出し3
#### 見出し4
##### 見出し5
###### 見出し6
本文
- 行頭にシャープ記号
#を記述する、ATX スタイルを使います- Setext スタイルはプレーンテキストでの見栄えは悪くありませんが、「見出し行を Grep したい」時に利便性が低いのでオススメしません
- 見出し行の前後には1行の空行を開けましょう
- プレーンテキスト表示時の可読性のため、「見出し1」「見出し2」の上には2行程度、空行を開けるなどしても良いかと思います
# 悪い例
悪い例。この本文と上の見出しとの間に空行がない
# 良い例
↑見出しの上に2行の空行、下は1行の空行。
## 良い例
このようにすると、見出しによる段落が表現できるでしょう。
- 「見出し1」はドキュメントのタイトルとして、1ファイル中に1回だけ使用することが望ましいでしょう。通常の見出しは「見出し2」から始めます
- ドキュメントタイトルを Frontmatter などで表現している場合は、「見出し2」から「見出し1」に繰り上げても良いでしょう
- ドキュメントのアウトラインは「見出し4」程度までに留めるようにしましょう
- ほとんどの場合、「見出し5」「見出し6」を使う機会はありません。それらが多数登場する場合は、アウトラインを整理する、ドキュメントを分割することを検討した方が、まとまった文書になるでしょう
段落 (p 要素)
- 段落の前後には1行の空行を開けましょう
- 行末に半角スペースを2つ配置することで「改行」(
br要素) を表現できますが、このような強制改行は原則として行わないでください (文章の折り返しはビューアや CSS に任せるべきです)
リスト (ul・ol 要素)
- 箇条書き
- 箇条書き
- ネストした箇条書き
- ネストした箇条書き
- さらにネストした箇条書き
- さらにネストした箇条書き
- リストとリストの間を開ける場合は、上のように2行の空行を設けます
- ただし、一般的にはリストとリストの間に何らかの段落があるべきです
1. 数字での箇条書き
2. 数字での箇条書き
3. 数字での箇条書き
- ネストした箇条書き
4. 数字での箇条書き
1. ネストした数字での箇条書き
2. ネストした数字での箇条書き
5. 数字での箇条書き
- 「見出しと段落」と同様、リストの前後も1行の空行を開けます
- 通常の箇条書きはハイフン
-で記述します- アスタリスク
*やプラス記号+でもリストになりますが、アスタリスクは強調構文でも使用されること、プラス記号は Wiki 記法で「順序付きリスト」に使われており混乱しやすいので、ハイフンを推奨します
- アスタリスク
- 箇条書きのネストには半角スペース4つを推奨します
- 通常の箇条書き同士であれば、2スペースでのネストが有効な場合もありますが、順序付きリストと通常のリストが混在する場合は4スペースでないとネストされません
- 「ネストされたリスト」だけを
grepしたくなった時にやりやすくなったりもしますので、4スペースに統一しておくと良いでしょう
- 順序付きリストは
1.の連続で記述してもパースされますが、プレーンテキスト表示時の可読性のため、インクリメントして記述することを推奨します
強調 (em・strong 要素)
通常の強調は*アスタリスク1つ*で行います。
強い強調は**アスタリスク2つ**で行います。
- 強調を実現する構文にはアスタリスク
*とアンダースコア_の2種類がありますが、アスタリスクを使用することを推奨します- CommonMark 仕様では、アンダースコアは前後をスペースで区切られていないと正しくパースされません。いわゆる Pedantic なパーサでは、分かち書きされていない文章でもアンダースコアによる強調が有効になりますが、本文中のアンダースコアを誤検知したりする可能性もあります
- アスタリスクは分かち書きしなくとも強調構文として認識されるため、分かち書きの文化がない日本語では、こちらに統一する方が良いでしょう
画像 (img 要素)
本文
本文
- リスト
- 
- リスト
- 画像は段落に1つだけ配置するか、リストに1つだけ配置するなど、シンプルな書き方にすることが望ましいでしょう
- テーブル内に画像を配置するなど、凝ったレイアウトにしようとするとパーサのバグを踏みやすいです
リンク (a 要素)
[Example](https://example.com/) このように書くと、「Example」という文章がリンク文字列になります。
<https://example.com/> このように書くと、URL がそのままリンクになります。
- ドキュメント内をキーワード検索した時に探しやすくなるよう、リンク先のページタイトルをリンク文字列として使用することが望ましいでしょう
- 「こちらのサイト」や「このページ」といったリンク文字列でリンクしないでください。昔からウェブアクセシビリティの観点で指摘されていることですが、「こちら」では読者にどのようなページなのか伝わりません
- 参考：よいHTML、わるいHTML：ウェブユーザビリティについて … 「リンクのアンカーを意味のある文にする」
引用 (blockquote 要素)
> 引用したいテキストの行頭に、大なり記号と半角スペース1つを記述します。
>
> 空行を作る場合は、上の行のように「大なり記号と半角スペース1つ」のみの行を記述してください。
>
> - [このように、引用中に他の記法を混ぜ込めます](https://example.com/)
- 参考文献へのリンクのみではなく、特に参考になった部分を引用しておくと良いでしょう
- ドキュメント内をキーワード検索した時に探しやすくなります
- リンク先ページが消失した際も、引用しておくことで必要な情報が引き続き確認できます
インラインコード (code 要素)
プロンプトに `yes` と入力すると、コンソールに `Done.` と出力されます。
- リンク記法にしたくない URL、コード、コンソール出力などを文章中に混ぜて記載する際に、インラインコード記法を使います
- Markdown 構文に勘違いされそうな記号を文章中に記載する場合も、インラインコード記法を使ってエスケープしておくと良いでしょう
- バッククォート記号自体をインラインコード記法で表現したい場合は、文字列を囲むバッククォートを2文字ずつ・3文字ずつなどに増やすことで対処できます
- ex.
ここに`バッククォート← これは｀｀ここに｀バッククォート｀｀と記述しています (全角バッククォートで表現) - ex.
`← バッククォートのみ記述するのは困難なので、｀｀(スペース)｀(スペース)｀｀と表記しています。もしくは直接 HTML を書いて<code>`</code>としても良いでしょう
コードブロック (pre 要素)
```javascript
const example = 'Hello World';
```
(上のサンプルは、行頭に4スペースを配置することでコードブロック記法にパースさせています)
- バッククォート3つ
```で囲んだ部分がコードブロックになります- 4スペースインデントすることでもコードブロックになりますが、「バッククォート3つ」の方がコードブロックを Grep しやすくなるのでよりオススメです
- コードブロックの開始時に
```javascriptのように言語名を指定しておくと、その言語でシンタックスハイライトしてくれるパーサもあったりします (CommonMark 仕様ではありません)
水平線 (hr 要素)
本文
---
本文
- ハイフン3つ
---で水平線になります。可読性のため前後には最低1行ずつ空行を開けましょう- プレーンテキストでの可読性のため、前後に2行ずつ空行を開けても良いでしょう
- ハイフンの数は3つ以上なら何個でも良いのですが、3つで固定しておくと Grep しやすくなります
テーブル記法 (table 要素)
テーブル記法は、CommonMark 仕様では定められていません。世間的によく見かけるのは GFM (GitHub Flavored Markdown) と呼ばれる CommonMark の拡張構文ですが、これに対応するパーサでないと正しく表示できません。
| 見出し | 見出し |
|--------|--------|
| 本文 | 本文 |
- 上のような書式が、一番クセが少なく、とりあえず表としてパースされる可能性が高い記法でしょう
- セル内の文章の前後は半角スペース1つ以上を開けます (
| 本文 |のように) - 見出し行とデータ部を区切る行のみ、
|---|と、バーティカルバーとハイフンの間にスペースを開けないようにすることで、見出し行との区切りが伝わりやすくなります - プレーンテキストでも読みやすくするため、適宜垂直アラインメントを整えると良いでしょう
- 巨大なテーブルは整形が大変なので、テーブルは小さく作りましょう
- 自動的にアラインメントを揃えてくれれるエディタツールもあります
- セル内の文章の前後は半角スペース1つ以上を開けます (
- コロン
:を用いてアラインメントを指定できる記法もありますが、パースできない場合も多くオススメしません - セル結合などは表現しきれないので、複雑なテーブルを書く必要がある場合は HTML で書いた方が良いでしょう
HTML を書くしかないもの
以下は CommonMark 仕様にない記法ですので、たまたま対応しているパーサを頼っていないか注意してください。
- 打ち消し線
- 一部のパーサではチルダで囲むと
~削除~の扱いになるものもありますが、CommonMark 仕様ではありません <del>削除する文章</del>と書きます
- 一部のパーサではチルダで囲むと
- 追記 (下線)
<ins>追記した文章</ins>と書きます
- 折りたたみ
details要素、summary要素、本文を実装します - 定義リスト
dl・dt・dd要素を自分で実装します
CommonMark 仕様を実際に試したい
上のサイトで Markdown テキストを入力すると、CommonMark 仕様に沿ってパースされたプレビューが確認できます。こちらを使って、CommonMark ではどのように解釈されるのか、ご利用のパーサとの比較をしておくと良いでしょう。
Markdown 文書をチェックしたい
Markdown 文書の構文をチェックしたり、読みやすい Markdown かどうかを判定してくれる、markdownlint というツールがあります。
上のサイトで Markdown テキストを入力すると、デフォルトの Lint 設定に基づき構文チェックをしてくれます。例えば
# 見出し
本文
このように入力すると、MD022 / blanks-around-headings : Headings should be surrounded by blank lines という警告を出してくれます。
# 見出し
本文
このように見出しと本文の間に空行を開けると、この警告が解消されます。
CLI として導入することもできます。npm パッケージとしてインストールする markdownlint-cli2 では、設定ファイルで Lint ルールを調整できるのでオススメです。
以上です
Markdown 文書はプレーンテキストでも読みやすく書くことで、メンテナブルで可読性の高い文書になります。
特定のパーサに依存しない、可搬性の高い文書にするには、多くの構文を使わず、平易なレイアウトに留めることが重要です。
これらは個人的なプラクティスでしたが、markdownlint などの Lint ツールを用いれば、チーム内で平仄を合わせることも可能ですので、より良い Markdown 文書を書くための仕組みづくりも検討されると良いでしょう。