「.md」ファイルって何？Markdown (マークダウン) のおさらい

今更かもしれないが、Markdown をおさらいする記事を書いてみようと思う。最近フロントエンド界隈に飛び込んで、「.md ファイルって何やねん？」となっている初学者向け。

Markdown とは

Markdown (マークダウン) とは、文書を記述するための軽量マークアップ言語のこと。

Markdown ファイル自体はプレーンなテキストで記述でき、HTML 形式に変換して閲覧できる。

Markdown の特徴

• プレーンテキストで記述できる
  • 記号と空行の組合せで、見出しや強調、リンクなどを示す
  • テキストファイルなので、Word や Excel のようなバイナリ形式のファイルよりバージョン管理がしやすい
• HTML 形式に変換できる
  • CSS との組合せ次第で見栄えを調整できる
  • ドキュメントを配布する時に相手の環境やソフトを問わない (誰でもすぐ読める)
• たとえ HTML 形式に変換しなくとも、プレーンな Markdown ファイルそのままでも読みやすくなるよう、構文が工夫されている

マークアップとはどういうことか

「Markdown はマークアップ言語の一種」と表現したが、この「マークアップ」とはどういうことか、これを押さえておくと「分かりやすい文書構成」にも繋がるので、おさらい。なお、多分に戸田奈津子意訳で書いていますので詳細はおググりください。

「マークアップ」は、出版業界の作業工程が語源。原稿用紙に、文章の各部分の書体や文字サイズなどの指示を書き込む作業のことを指した。

次第にコンピュータが登場し、政府の公文書や航空機のマニュアルなど、大規模なドキュメント群を効率的に管理する仕組みが求められた。そこで、文章の各部分を「タグ」で囲んで意味付けをしたり、他のドキュメントの参照を示したりできる仕組みとして、SGML や HTML (HyperText Markup Language) といったマークアップ言語が登場した。「他のドキュメントの参照」というのが、HTML における「ハイパーリンク」の概念・仕組みに繋がっている。数学の論文などは、TeX (テフ) という組版処理システムが有名。

HTML およびハイパーリンクの概念が発展し、World Wide Web という仕組みとなって一般化したことで、こんにちではインタラクティブな Web ページも多く見られるが、HTML の大元の役割としては「文章への意味付け」「文書構造の表現」が目的である。すなわち、「この文章は見出し」「この言葉は略語」「この文言から他のドキュメントに遷移する」といった意味を文書の各部分に与えていくことが「タグ付け」であり、「文字を大きくする」「赤色にする」「アニメーションで移動させる」といった視覚的な表現を指定するものではないことに注意したい (HTML 文書に対する見栄えの指定は CSS で行う)。

さて、HTML というマークアップ言語が世間に広まったものの、「純粋に文書を執筆する際の効率」という面では、HTML を記述するのは相当に非効率である。そこで考案されたのが、Markdown をはじめとする「軽量マークアップ言語」だ。HTML の文法をより簡素にして、マークアップの負担を減らしつつ、最終的には HTML として出力できるよう考慮されている。

最終的には HTML、すなわち文章の意味や構造を適切に示したドキュメント (文書) として出力することを踏まえると、Markdown の場合も、その構文を正確に理解し、適切に使いこなせるようになりたい。

Markdown を書くための環境

Markdown はプレーンテキストで記述できるので、執筆自体は「メモ帳」のようなシンプルなテキストエディタで可能。

フロントエンド開発でよく使われているエディタ「VSCode」は標準で Markdown プレビュー機能があるので、HTML 形式に変換した時の様子を確認しながら執筆できる (時折制御文字が混じるバグがあるので注意したいが…)。Markdown をプレビュー表示しながら執筆できるテキストエディタ (Markdown エディタ) は他にもあるので各自お好みで。

Markdown を読むための環境

Markdown はそのままでも読みやすい記法が採用されているので、HTML 形式に変換せずともエディタ上で直接読めてしまったりする。とはいえ HTML に起こして綺麗に整形したいと思うので、「Markdown パーサ」「Markdown ビューワ」を導入したい。

一番手軽なのは VSCode のプレビュー機能。他に Google Chrome ブラウザの拡張機能として「Markdown Viewer」という拡張機能があったりするので、エディタ同様コチラもお好みの環境で。

Markdown の基本構文

詳細は各種解説サイトを。

# 見出し1 (h1)

## 見出し2 (h2)

### 見出し3 (h3)

#### 見出し4 (h4)

##### 見出し5 (h5)

###### 見出し6 (h6)

通常の文章 (p)

通常の文章中で強制改行したいときは  
文章末尾にスペースを2つ入れる (br)  
※ 基本的に強制改行は使わないこと。見栄えのための改行であれば不要。段落として文章の意味を区切るべきではないか考慮すること

- リスト (ul)
  - リストのネスト (スペース2つか4つ)
  - リストのネスト (「ネスト」の意味分かってますか？)
      - リストをさらにネスト
  - リストのネスト
- リスト
- リストはハイフンではなくアスタリスクでも書けるが、アスタリスクは強調構文の記号としても使うので混同を避けるためハイフンを推奨。

リスト (ul) と順序付きリスト (ol) が連続する場合は2行以上空行を開けないと、同じリストとして扱われてしまう。

1. 順序付きリスト (ol)
2. 順序付きリスト
    1. 順序付きリストをネストする際はスペース4つ単位
    2. 順序付きリストのネスト
3. 順序付きリスト

｀｀｀
コードブロック (pre > code)。サンプルのためバッククォートを全角で書いているが、半角で書くこと。
｀｀｀

｀｀｀html
<div>
  <span>コードブロック開始のバッククォート3つの直後に言語名を書くとシンタックスハイライトできる</span>
</div>
｀｀｀

> 引用ブロック (blockquote)
> 
> - 引用ブロック内にリスト

---

↑ 水平線。

ココからはインライン要素。

文章の*強調* (em)。文章を**さらに強調** (strong)。アンダースコアでも書けるが、「分かち書き」が必要になるパーサが多いので、アスタリスクの方が良いかも。

[リンクする場合](http://example.com/)。インラインコード → `<code>`。

![画像。ココのテキストは Alt Text。](http://example.com/example.gif)

「分かち書き」の仕様については以下の記事にまとめた。

• Markdown の強調構文で使う「アスタリスク」と「アンダースコア」の違い

Markdown 記述時の主な注意点

• 見出し・リスト・テーブル・引用ブロック、コードブロックなど、「段落」や「ブロック」を示す箇所は、改行ではなく「空行」を開けること。
  • なぜか空行を開けず、改行のみで詰めて書きたがる人がいたりするのだが、改行と空行 (による段落表現) では文章の意味合いが変わってしまうので、必ず空行を作ること。

良い例：

# 見出し見出し　↓ココに空行を開けている

本文本文本文…　↑ココに空行を開けている

- リストリスト　↑ココにも空行
- リストリスト　↓ココにも空行

> 引用ブロック　↑ココにも空行

本文本文本文…　↑やっぱり空行

悪い例：

# 見出し見出し　↓空行がない
本文本文本文…　↑空行がない
- リストリスト　↑空行がない
- リストリスト　↓空行がない
> 引用ブロック　↑空行がない
本文本文本文…　↑空行がない

• Markdown の構文に関する「単一の標準仕様」はない。
  • 現状「CommonMark」プロジェクトによる標準化が進んではいるが、世の Markdown エディタやパーサが全てこの仕様に準拠しているというワケではない。
  • よく知られるテーブル記法は GitHub Flavored Markdown (GFM) という GitHub による派生言語だったりする。
  • よって、あまり複雑な構造にしたり、特殊な構文を使ったりすると、他の人が使用するパーサで正しく表示されない恐れがある。なるべく平易な構造になるよう、ドキュメントの構成を考える必要がある。
  • どうしても Markdown の一般的な構文で表現しきれない内容を書きたい場合は、Markdown 内に HTML を記述することもできるので、直接 HTML で書いてしまった方が良いだろう。

以上。手軽に書ける Markdown の紹介でした。