FlowingDev

Markdown入門：ただのテキストがマントを羽織った話

Markdownがアスタリスクやハッシュタグのようなシンプルな記号を使って、プレーンテキストを美しい書式のドキュメントやウェブページ、メッセージに変える方法を学びましょう。

ツールを試す: Markdown ビューア

一言で言うと

Markdownとは、複雑なコードや面倒なボタン操作の代わりに、読みやすいシンプルな記号を使って、リッチな書式（太字、リスト、リンクなど）のテキストを書けるようにする記法（シンタックス）のことです。

Markdownが解決する問題

テープを2000年代初頭まで巻き戻してみましょう。当時、ウェブ用に何かを書こうと思ったら、2つのイケてない選択肢しかありませんでした。選択肢A：生のHTMLを書く。これは、<p>や<strong>、<ul>、<li>といった、山ほどあるタグを手で入力していくことを意味しました。時間がかかり、エラーも起きやすく、おまけにソーステキストはまるでロボットのくしゃみのような見た目になってしまいました。選択肢B：初期のブログプラットフォームやMicrosoft Wordの「HTMLとして保存」機能にあったような、「WYSIWYG（ウィジウィグ、What You See Is What You Get）」エディタを使う。これらは、肥大化して汚く、非標準的なHTMLを吐き出すことで悪名高く、謎の挙動で表示が崩れることもしばしばでした。

どちらの選択肢も、実際に文章を書く人にとっては良いものではありませんでした。

2004年、このジレンマを解決するために、作家のJohn Gruberが、故Aaron Swartzの協力のもとMarkdownを開発しました。彼らの中核にあった哲学は、過激なものでした。それは「加工前のプレーンテキストの状態でも、書式設定用のタグに邪魔されることなく、可能な限り読みやすいこと」というものです。目標はHTMLを置き換えることではなく、書くことを第一に考え、クリーンなHTMLに変換しやすい記法を作ることでした。

<strong>これを見て！</strong>と書く代わりに、**これを見て！**と書くだけでよくなりました。リストを作るのに<ul>と<li>タグのごちゃごちゃした塊と格闘する代わりに、アスタリスクを使うだけでよくなったのです。コンピュータより、まず人間を第一に考えて設計されたのです。この思想が、ブログ記事やコメント、フォーラム、そして特にプロジェクトのドキュメントに最適だったのです。

内部での仕組み

あなたがエディタにMarkdownを打ち込み、隣にきれいなプレビューが表示されるとき、そこでは、パース（解析）とレンダリング（描画）という2つのステップからなるダンスが繰り広げられています。「Markdownビューア」や「エディタ」は、このダンスをリアルタイムで実行してくれるツールに過ぎません。

パーサー：記号から構造へ

最初のステップはパースです。パーサーと呼ばれるプログラムが、あなたの書いたプレーンテキストのドキュメントを上から下まで読み込みます。単に単語を読んでいるわけではありません。Markdownの記法を定義する特殊文字を探しているのです。

  • 行頭に## My Great Ideaという記述を見つけると、「なるほど！これはただのテキストじゃない。レベル2の見出しだ」と考えます。
  • * で始まる行を見つけると、それをリストの項目の始まりとして認識します。
  • **this**のように二重アスタリスクで囲まれたテキストを見つけると、「強い強調」（太字）のフラグを立てます。

この処理を行う際、パーサーは直接HTMLを生成しているわけではありません。その代わりに、ドキュメントの構造を内部的に表現したもの、しばしばAbstract Syntax Tree（AST、抽象構文木）と呼ばれるものを構築しています。設計図のようなものだと考えてください。この設計図には<h2>タグはありません。代わりに、「レベル」が2で、内容が「My Great Idea」である「見出し」ノードが存在します。

このプロセスを単純化すると、以下のようになります。

あなたの書いたMarkdown:

## Shopping List

- Milk
- **Important**: Bread

単純化されたAST（設計図）:

Document
└── Heading (level 2, content: "Shopping List")
└── UnorderedList
    ├── ListItem (content: "Milk")
    └── ListItem
        └── Text (content: " ")
        └── Strong (content: "Important")
        └── Text (content: ": Bread")

レンダラー：構造からHTMLへ

パーサーがASTという設計図を作り終えたら、レンダラーの出番です。レンダラーの仕事は、そのツリー構造をたどって、各ノードを最終的なフォーマット（通常はHTML）に変換することです。

  • Headingノード（レベル2）を見て、<h2>Shopping List</h2>を出力します。
  • UnorderedListノードを見て、その内容を<ul>と</ul>で挟みます。
  • ListItemノードを見つけて、<li>と</li>でラップします。
  • Strongノードを見て、その内容を<strong>と</strong>でラップします。

結果として生成されるHTML:

<h2>Shopping List</h2>
<ul>
<li>Milk</li>
<li><strong>Important</strong>: Bread</li>
</ul>

このクリーンなHTMLがWebブラウザ（あるいは最終的な出力を表示するなにか）に渡され、それを使って、あなたが実際に目にするフォーマット済みのテキストがレンダリングされるのです。

フレーバーと拡張機能（「CommonMark」という妥協案）

Gruberの最初の仕様書は、いくつかの点で少し曖昧でした。「リストの中に引用ブロックを入れ、さらにその中に別のリストを入れるとどうなるか？」といった問いに対して、パーサーによって答えが異なりました。このため、それぞれが独自の小さな調整や拡張機能を持つMarkdownの「フレーバー（方言）」が乱立することになりました。

機能 オリジナルMarkdown GitHub Flavored Markdown (GFM)
テーブル なし あり
取り消し線 (~~text~~) なし あり
タスクリスト (- [x]) なし あり
フェンスされたコードブロック (``````) なし あり

現在、圧倒的に人気のあるフレーバーは**GitHub Flavored Markdown (GFM)**です。これは、テーブル、シンタックスハイライト付きコードブロック、タスクリストなど、開発者のコラボレーションに不可欠な機能を追加したものです。フレーバーが乱立したことで、新たな問題が生まれました。書いたテキストが、GitHubとStack Overflowで表示が異なってしまう、といった問題です。

これを解決するため、開発者たちのグループがCommonMarkというイニシアチブを立ち上げました。これは、非常に詳細で曖昧さのないMarkdownの仕様書を作成するプロジェクトです。現在、ほとんどのモダンなMarkdownパーサーはCommonMarkとの互換性を目指しており、GFMはその人気なスーパーセット（上位互換）となっています。

実話から学ぶ

プロジェクトを救ったREADME

ある開発者、仮にプリヤさんとしましょう、が新しいチームに加わりました。コードベースは複雑で、最初の作者たちはとっくに会社を去っていました。パニックになりかけたその時、彼女はそれを見つけました。プロジェクトのルートディレクトリにあるREADME.mdです。それは単なるファイルではなく、命綱でした。明確な見出しを使ってプロジェクトの目的が説明され、「はじめに」のセクションでは、番号付きリストでセットアップ手順が正確に示されていました。重要なコマンドは、完璧にシンタックスハイライトされたコードブロックで提示されていました。「トラブルシューティング」のセクションには、よくあるエラーとその解決策まで書かれていました。プリヤは、数日かかるかと思われた作業を1時間もかからずに終え、自分のマシンでプロジェクトを動かすことができたのです。

教訓： README.mdファイルに書かれたMarkdownは、開発者のオンボーディングを行い、プロジェクトをアクセスしやすくするための、最も効果的な単一のツールです。そのシンプルさが、開発者たちにドキュメントを実際に書き、メンテナンスする気を起こさせます。

WYSIWYGを捨てたブロガー

アレックスさんは技術ブログを運営していましたが、使っているCMS（コンテンツ管理システム）に組み込まれたエディタが大嫌いでした。動作は遅く、コードスニペットを貼り付けるとフォーマットが崩れる悪夢に見舞われ、生成されるHTMLはめちゃくちゃでした。そんな時、アレックスさんはMarkdownを発見し、天啓を得ました。彼はすべての記事を、ローカルマシン上の執筆に集中できるシンプルなテキストエディタで書き始めました。テキストはクリーンで、コードブロックは完璧、そしてただの.mdファイルなのでGitでバックアップも取れます。記事の準備ができたら、生のMarkdownをCMS（幸いにもMarkdown入力モードがあった）にコピー＆ペーストするだけ。彼はより速く、ストレスなく執筆できるようになり、コンテンツは一つのプラットフォームに縛られることなく、完全にポータブルになりました。

教訓： Markdownは、あなたのコンテンツをプレゼンテーション（見た目）から切り離します。普遍的なプレーンテキスト形式で書くことで、あなたは自分の成果物を所有し、ツールやプラットフォーム間で簡単に移動させることができるのです。

非開発者によるプルリクエスト

ある小さなスタートアップのマーケティングチームが、一般公開されているAPIドキュメントのサイトに、目に余る誤字があることに気づきました。ドキュメントはGitHubでホストされており、ファイルはすべてMarkdownでした。HTMLもGitも全く知らないプロダクトマネージャーが、GitHubのウェブサイト上で該当ファイルにたどり着き、「編集」ボタンをクリックすると、そこには人間が読めるMarkdownのテキストがありました。彼は誤字を修正し、変更内容を説明するコメントを加え、「変更を提案する」をクリックしました。これによりプルリクエストが作成され、開発者がすぐにレビューしてマージしました。修正は数分で本番に反映されたのです。

教訓： Markdownの可読性は、コラボレーションへの参入障壁を下げます。技術者でないチームメンバーが、開発者になることなく、ドキュメントやウェブサイトなどに直接貢献することを可能にするのです。

よくある間違いと落とし穴

  • 空行を忘れる。 これは「なぜリストが表示されないんだ！？」の第一の原因です。リスト、引用ブロック、コードブロックなど、多くのMarkdown要素は、正しく解釈されるために直前に空行を必要とします。あなたの目にはリストに見えても、パーサーはその空行がないと文脈を切り替えられません。

  • リストのインデントが不統一。 サブリストを作成するとき、インデントに使うスペースの数が重要になります。CommonMarkの仕様では、2スペースか4スペースのインデントが一般的です。タブとスペースを混ぜたり、インデントの幅がバラバラだったりすると、リストの構造が壊れてしまいます。

  • 自分の使っているフレーバーが万国共通だと思い込む。 GFMのパイプ構文（| Head | Head |）を使って美しいテーブルを作成し、それを標準のMarkdownしかサポートしていないシステムに貼り付けると、どうなるでしょう。結果は、パイプとハイフンがごちゃ混ぜになった無残な表示です。常に、ターゲットとなるプラットフォームがどのフレーバーをサポートしているかを意識しましょう。

  • 改行は段落ではない。 ソースファイルでエンターキーを1回押して次の行に移っても、通常、レンダリングされた出力では新しい段落は作られません。単に前の行と連結されます。本当の段落区切り（<p>タグ）を作るには、完全な空行（つまりエンターキーを2回押す）が必要です。強制的に改行（<br>タグ）を入れたい場合は、行末に2つのスペースを置いてからエンターキーを押します。

  • 特殊文字をエスケープしない。 イタリックにならずに、文字通り*literally*と書きたい場合はどうしますか？ バックスラッシュで特殊文字を「エスケープ」する必要があります：\*literally\*。これは、#、_、[、]など、構文上の意味を持つ他の文字にも当てはまります。

なぜMarkdownを気にかけるべきか

書くのも読むのも簡単で、特定のフォーマットに縛られない書式付きテキストが必要なときはいつでも、Markdownを思い浮かべるべきです。それは、開発者コミュニケーションの共通言語なのです。

  • プロジェクトドキュメンテーション： すべてのREADME.md、CONTRIBUTING.md、Wikiページ。
  • メモを取る： Obsidian、Joplin、BearのようなツールはMarkdownベースで構築されており、ポータブルでリンク可能な個人用ナレッジベースを作成できます。
  • コンテンツ作成： 静的サイトジェネレーター（Jekyll、Hugo、Eleventyなど）や「ヘッドレス」CMSのための執筆。
  • 日々のコミュニケーション： GitHub/GitLabでのIssueやプルリクエスト、コメントの作成。Stack Overflowでの質疑応答。SlackやDiscordでのチャット。

Markdownは、.txtの辛いほどのシンプルさと、.docxや生のHTMLの過剰な複雑さとの間の、絶妙なスイートスポットを突いています。現代のソフトウェア開発とデジタルコミュニケーションにおける、基本的なツールなのです。

もっと深く知るために

理論はOK。さあ手を動かそう — 100%ブラウザ内で。

ツールを試す: Markdown ビューア