ファイル形式
Markdownとは？記法、CommonMark、GFM
Markdownは、いくつかの記号だけでプレーンテキストに見出し、リスト、リンクを加えられる軽量マークアップ言語です。その歴史と規格、MDファイルをWordやPDFに変換したときに残るものを解説します。
著者: Hemen Dönüştür Editör Ekibi公開日: 10 分で読めます
ソフトウェアプロジェクトのREADME、メモアプリの見出し付きリスト、チャットアプリでアスタリスクを使って太字にした単語を思い浮かべてください。その裏にはすべて同じ考え方、Markdownがあります。Markdownは、プレーンテキストにいくつかの簡単な記号を加えるだけで、見出し、リスト、リンク、表を定義できる軽量マークアップ言語です。ファイルはどのテキストエディターでも読めるままなのに、必要なときにはきれいなHTMLページ、Word文書、PDFに変換できます。この記事では、Markdownの成り立ち、基本の記法、CommonMarkとGitHub Flavored Markdownの違い、MDファイルを変換するときの注意点を説明します。
Markdownとは
Markdownは、書き方の約束事の集まりであると同時に、その約束事で書かれたテキストをHTMLに変換するツールの総称でもあります。ファイルは通常、.mdまたは.markdownという拡張子で保存されます。作者のジョン・グルーバーによれば、設計で最も重視されたのは読みやすさです。Markdownの文書は、タグや書式の命令で印付けされているようには見えず、プレーンテキストのままで公開できるものであるべきだというのです。HTMLなら<strong>重要</strong>と書くところを、Markdownでは**重要**と書き、元のままでも自然に読めます。
簡単な歴史
ジョン・グルーバーは2004年にMarkdownを作り、アーロン・スワーツがアイデアの相談相手として協力しました。記法は、プレーンテキストのメールの慣習（強調にアスタリスク、リストにハイフン）や、setextやTextileといった以前のマークアップ言語を参考にしています。グルーバーが自身のサイトDaring Fireballで公開したPerlスクリプトMarkdown.plのバージョン1.0.1は、2004年12月17日付けです。
ただし、グルーバーの説明は正式な仕様ではなく、例による解説でした。あいまいなケース（入れ子のリスト、インデントによるコードブロック、HTMLの混在）では実装ごとに独自の選択がなされ、同じテキストがツールによって違う出力になるようになりました。これに対して、大きく2つの動きが生まれます。
- CommonMark（2014年）：ジョン・マクファーレンが主導した仕様で、Markdownをあいまいさなく定義し、数百の例でテストできるようにしました。最初のバージョンは2014年秋に登場し、現在のバージョンは2024年1月28日付けの0.31.2です。仕様はまだ1.0と宣言されていません。
- GitHub Flavored Markdown（GFM、2017年）：CommonMarkの上に作られたGitHubの正式な仕様です。表、タスクリスト、取り消し線、拡張自動リンク、そしてセキュリティのための一部の生HTMLタグのフィルタリングといった拡張を加えています。公開されている最新の仕様は、2019年4月6日付けの0.29-gfmです。
Markdownはインターネットの基盤でも認められました。2016年3月に公開されたRFC 7763は、text/markdownというメディアタイプ（MIMEタイプ）を登録し、作者が意図したMarkdownの種類を示す任意のvariantパラメーターも定めています。
主なMarkdownの派生
CommonMarkとGFMのほかにも、広く使われている派生があります。RFC 7763と同時に公開されたRFC 7764は、そのいくつかを登録し、使い方の指針を示しました。
- Markdown Extra：脚注、定義リスト、表を加えた初期の拡張。
- MultiMarkdown：メタデータ、引用、相互参照を備えた、学術的な執筆向けの派生。
- Pandoc Markdown：変換ツールPandocで使われる種類で、書籍や論文の執筆向けの拡張が多数あります。
実用的な目安として、文書が見出し、リスト、リンク、コード、単純な表だけを使っているなら、ほぼどこでも同じように表示されます。脚注、定義リスト、特殊なブロックに頼るなら、表示先の環境がどの派生に対応しているかを確認しましょう。
基本の記法
日常的に必要なMarkdownの部分は、数分で覚えられます。
# レベル1の見出し
## レベル2の見出し
この段落には**太字**、*斜体*、`コード`があります。
- 箇条書きリスト
- 2つ目の項目
- インデントしたサブ項目
1. 番号付きリスト
2. 2つ目の手順
[リンクのテキスト](https://example.com)
> 引用
```
複数行のコードブロック
```GFMで追加された表とタスクリストは次のようになります。
| 形式 | 拡張子 |
|--------|-----------|
| Markdown | .md |
| プレーンテキスト | .txt |
- [x] 下書きを書く
- [ ] 見直す段落は空行で区切ります。1つの改行は、ほとんどの実装で同じ段落の一部として扱われます。強制的に改行したいときは、行末にスペースを2つ置きます。Markdownの中にHTMLを直接書くこともできます。CommonMarkはこれを認めていますが、GFMのような環境ではセキュリティのため一部のタグがブロックされます。
Markdownが使われる場面
- ソフトウェア開発：README、変更履歴、コントリビューションガイド、そしてGitHubやGitLabなどのプラットフォームでのissueやコードレビューのコメント。
- 技術ドキュメント：MarkdownファイルからWebサイトを作る静的サイトジェネレーター。
- メモ：多くのメモアプリがメモをMarkdownで保存したり書き出したりします。
- チャットやコミュニティのプラットフォーム：RedditやDiscordなどのプラットフォームはMarkdownの派生を使っています。
- 執筆と出版：Pandocのようなツールで、1つのMarkdownからHTML、PDF、DOCX、EPUBを作成。
- AIツール：チャット型のAIアシスタントは、回答をMarkdownで整形することがよくあります。
長所と短所
| 長所 | 短所 |
|---|---|
| 元のままでも読みやすい | 派生によって動作が異なる |
| プレーンテキストなので小さく、持ち運びやすく、バージョン管理と相性がよい | フォント、色、ページレイアウトがない |
| HTML、PDF、Wordに簡単に変換できる | 複雑な表（結合セル）が作れない |
| 数分で覚えられる | 画像は別ファイルになる |
| 特定のプログラムに縛られない | 空白やインデントの間違いで出力が変わる |
Markdownを開けるソフト
Markdownはプレーンテキストなので、メモ帳やテキストエディットを含め、どのテキストエディターでも開けます。整形されたプレビューを見るには、Visual Studio Code内蔵のMarkdownプレビューや、ObsidianやTyporaといった専用エディターを使えます。GitHubとGitLabは、リポジトリ内の.mdファイルを自動で整形して表示します。一方、WordはMarkdownを書式付きのテキストとしては開かないので、先に変換が必要です。
よくあるトラブルと対処法
リストや見出しが表示されない
CommonMarkでは、見出しの記号の後にスペースが必要です。##見出しではなく## 見出しと書きます。段落の直後のリストも、正しく表示するには間に空行が必要なことがよくあります。
行がつながってしまう
1つの改行では段落は分かれません。新しい段落にするには空行を入れ、段落内で改行するには行末にスペースを2つ置きます。
あるプラットフォームでは表が表示されるのに、別のところでは表示されない
表は、グルーバーの元のMarkdownにもCommonMarkの中核にも含まれておらず、GFMなどの拡張によるものです。表示先のプラットフォームがどの種類に対応しているかを確認してください。
数字で始まる段落が番号付きリストになる
「2024. was a busy year」のような行は、数字とピリオドで始まるのでリストとして解釈されることがあります。ピリオドをバックスラッシュでエスケープ（2024\.）すれば防げます。
Markdownファイルを変換するときのコツ
当サイトの変換ツールでは、Markdownファイルは当サイトのサーバーにアップロードされ、30分以内に削除されます。読み込みには、CommonMarkとGitHub風の拡張（表、タスクリスト、脚注、自動リンク）を有効にしたMarkdigライブラリを使っています。
- MarkdownからPDFへの変換とMarkdownからWordへの変換では、見出し、リスト、コードブロック、引用、罫線付きの表が保たれます。タスクリストのチェックボックスは、WordやPDFでも見えるよう☑と☐の文字に変換されます。本文は標準で12ptのセリフ体、コードブロックは等幅フォントで組まれます。
- MarkdownからHTMLへの変換は、READMEを文字コードが宣言された単体のWebページにします。
- 逆方向では、WordからMarkdownへの変換、HTMLからMarkdownへの変換、PDFからMarkdownへの変換でGitHub互換のMarkdownが作られます。見出し、太字と斜体、リスト、表、リンク、コードブロック、引用は保たれ、フォント、色、ページレイアウトは削除されます。GFMの表には見出し行が必須なので、見出し行のない表では1行目が見出しになります。「1. 条項」のように数字で始まる普通の段落は、誤ってリストにならないようエスケープされます。ファイルはBOMなしのUTF-8で保存されます。
よくある質問
MDファイルを開くには？
どのテキストエディターでも開けます。整形された状態で見たいなら、Visual Studio CodeのプレビューかMarkdownエディターを使いましょう。Wordで読みたい場合はDOCXに変換してください。
CommonMarkとGitHub Flavored Markdownの違いは何ですか？
CommonMarkは、Markdownの中核となる記法を厳密な規則で定義しています。GFMはその上位互換で、CommonMarkに表、タスクリスト、取り消し線、拡張自動リンクなどの拡張を加えたものです。
Markdownで表は作れますか？
はい。GFMなどの拡張を使えば、縦棒とハイフンで単純な表を書けます。結合セルのような複雑な構造には、HTMLの表を使うか、Wordで文書を作ってください。
MarkdownとHTMLの違いは何ですか？
Markdownは、HTMLに変換することを前提に作られた、よりシンプルな書式です。HTMLで表現できることすべてを表せるわけではありませんが、元の状態がずっと読みやすいのが特長です。必要なら、Markdownの中にHTMLを書くこともできます。
Markdownに公式の規格はありますか？
グルーバーの元の説明は正式な仕様ではありません。現在最も広く受け入れられている厳密な定義はCommonMarkで、text/markdownというメディアタイプは2016年3月にRFC 7763で登録されました。
