{"canonical_url":"https://engineer.company/ja/glossary/markdown/","content_markdown":"# Markdown\n\n## どのようなものか\n\nMarkdownは、文書を普通のテキストファイルとして書く方法です。強調する語をアスタリスクで囲む、見出しの前にハッシュ記号を置く、箇条書きの各項目をハイフンで始める、リンクに角括弧と丸括弧を続けるといった、少数の書き方が、どのHTMLを作るかを変換器に伝えます。名前は、構文と、最初に公開された変換プログラムの両方を指します。ファイルの拡張子は、通常`.md`か`.markdown`です。CommonMarkやGitHub Flavored Markdown（GFM）など、後から生まれた方言も、Markdownと呼びます。\n\nJohn Gruberが2004年にAaron Swartzと協力して開発し、最初の変換器をPerlで書きました。最終リリースMarkdown 1.0.1の日付は、2004年12月17日です。掲げた最優先の目標は、読みやすさでした。文書は、普通のテキストのまま公開でき、タグや書式命令でマークアップしたようには見えないものにすべきだと考えていました。構文に最も大きく影響したのは、既に使われていた、プレーンテキストの電子メールの書式だと書いています。構文にないものは、切り替えや区切り記号なしに、文章の中にHTMLを書きます。彼の考えでは、Markdownは書く形式、HTMLは公開する形式だからです。\n\n数行で、大半が分かります。\n\n```markdown\n移行は**一晩**、手順は三つでした。\n\n- 書き込みを止める\n- `pg_dump`でデータをコピーする\n- [アプリケーション](https://example.com/app/)の接続先を新しいホストにする\n```\n\n変換器は、これを、`strong`要素のある段落、三項目の一覧、インラインのコード、リンクに変えます。元の文章は、誰かが入力したメモとして、そのまま読めます。\n\n## なぜ重要なのか\n\nソース自体が文書であり、普通のテキストは、周りのどの道具より長く残ります。Markdownファイルは、どのエディターでも開け、版管理で行ごとの差分を比べ、プルリクエストでも明確にレビューできます。提供元が形式を廃止することはできず、まとまった文章を別のシステムに移すには、ファイルをコピーするだけです。\n\n代価は、曖昧さです。CommonMarkプロジェクトは、Gruberの説明は構文を一意に定めず、スクリプトには不具合があり、最後の更新も2004年12月だったため、2014年には、何十もの実装が、それぞれ違う方法で隙間を埋めていたと明言します。例は、GitHubのwikiと、PandocでDocBookに変換した場合とで、別の形になる文書です。Markdownは、どの入力も構文エラーとして拒否しないので、違いは、誰かが出力を見て初めて分かります。同プロジェクトは、同じ入力を二十を超える実装に通し、一致するかを見るBabelmark 3を挙げます。\n\n2014年に始まったCommonMarkは、John MacFarlaneの仕様で応えます。規則ごとに、入力と、それが出すべき正確なHTMLの例を結び付けます。2024年1月28日付の0.31.2には、652例あります。GitHubは、独自の方言GFMをCommonMarkの厳密な上位集合と定義し、表、タスクリスト項目、取り消し線、拡張した自動リンク、少数の生HTMLタグを無効にするフィルターを加えます。HugoのMarkdown変換器Goldmarkは、CommonMark仕様に準拠し、GFMにも対応します。\n\n通信上の名前もあります。2016年3月のRFC 7763は、構文の系統全体に`text/markdown`を登録しました。`charset`は必須で、ファイルがどの方言かを表す`variant`パラメーターは任意です。\n\n## 実際の活用例\n\nこのサイトで手作業で作成するページはMarkdownで、Goテンプレートが配置を決めます。[クレジットのページ](/ja/credits/)は、両方を静的サイト生成器Hugoと並べ、ページを作る道具として挙げます。同じページには、ソースの正しさを保つリンターとしてmarkdownlintも載せています。すべての診断をエラーとする品質ゲートの一部です。\n\n[AIエージェントに読めるサイトにするページ](/ja/ai-ready/)は、形式を逆向きに使います。ここのすべてのページには、同じアドレスにMarkdown版があり、`index.md`を足すか、`text/markdown`を要求して取得します。ビルドは、すべてのMarkdown版に不要なマークアップが残っていないかを読み、間違いがあれば公開を拒否します。そのページのMarkdown版も、一回のリクエストで取れます。\n\n```sh\ncurl -sL https://engineer.company/ja/ai-ready/index.md\n```\n\n[約50,000語のソフトウェア文書](/ja/portfolio/wrote-50000-words-of-software-documentation/)を、GitHub、Craft、ConfluenceでMarkdownにし、多くを人の手で執筆しました。何度も質問されていたアーキテクチャー、手順、使い方を扱い、版管理し、見つけられる状態に保ち、新しく入った人が早く仕事を理解できるようにしました。\n\n## 問題が起きるところ\n\n**太字がアスタリスクのまま表示されます。** 太字にするはずの語の両側に二つずつアスタリスクが見えても、HTMLは正しく、リンクも動くため、検査はすべて成功します。CommonMarkは、開始側の条件（left-flanking）を満たすアスタリスクの並びでのみ強調を開始します。その並びの直後に、リンクの角括弧のような句読記号が続く場合は、並びの直前に空白か句読記号がある場合だけです。前に文字があると、アスタリスクはそのまま残ります。Markdownを解析する前に、テンプレートエンジンが置いたものも同じです。Hugoは、ショートコードを、英数字の仮の文字列に置き換えます。このサイトのMarkdown版テンプレートには、ショートコードと隣の太字の間の空白を消したことで、三言語の60項目の太字が壊れた記録があります。空白を保ち、ソースではなく表示したページを確認します。このサイトの品質ゲートは、ビルドしたHTMLを読み、Markdownが記号のまま読者に届いていないかを検査します。\n\n**同じファイルが、二通りに変換されます。** 入れ子の一覧が、一方で平坦になり、他方では入れ子のままだったり、行頭のハッシュ記号が、一方で見出しになり、他方では文字のままだったりします。Markdownには報告すべき構文エラーがないので、何も知らせません。原因は方言の違いで、二つの変換器が、元の曖昧な箇所を違う方法で埋めています。使う方言を明記します。多くはCommonMarkかGFMです。それに従わせるリンターを使い、不確かな入力は、頼る前に複数の実装に通します。\n\n**ページのMarkdown版に、HTMLが入ります。** テキスト版の読者が、生の`svg`要素や、先頭のプラス記号が数値文字参照になった電話番号に出会います。Webページ用のHTMLを出す部品は、別の指示がなければ、ほかのすべての形式にも同じHTMLを出します。Hugoは、出力形式別にショートコードのテンプレートを探し、なければHTML版を使います。このサイトのショートコードテンプレートは、両方の事例を記録します。クレジットのMarkdown版の生の`svg`要素49個と、HTML用にエスケープされた連絡先ページの電話番号です。今は、マークアップを出すショートコードに、Markdown出力専用のテンプレートを用意します。品質ゲートは、コードを除き、Markdown版に生のHTMLもHTML実体参照も含まれないことも確認します。\n\n**生のHTMLがページから消えます。** Markdown内のHTMLブロックが、ソースは正しそうなのに、ビルドしたページにはありません。Gruberの構文は、文章のどこにでもHTMLを置けますが、変換器は拒否できます。HugoのGoldmarkの`unsafe`は既定で無効なので、Markdownに混ぜた生HTMLは表示されません。GFMは、`script`や`iframe`など、少数のタグをエスケープし、文字として表示します。代わりに、Hugoならショートコードや描画フックなど、生成器の機能を使うか、設定を意図的に有効にし、通すものを受け入れます。\n\n**リンターは、無視するよう指示されたものを通します。** 構造の壊れたMarkdownが、markdownlintの指摘なしにレビューを通ります。検出するはずの規則が設定で無効になり、理由も書いていません。このサイトの開発規則には、以前、markdownlintの設定に、コメントなしで六つの規則を無効にしたJSONファイルを使っていたことと、六つを調べると、二つが実際の不具合を隠していたことが記録されています。無効にする規則の横に、コメントを書ける形式で理由を残します。次の人が、その理由に異議を唱えられるようにするためです。\n\n## 参考資料\n\n- [CommonMark仕様](https://spec.commonmark.org/) — 規則ごとに、入力と、それが出すべきHTMLの例を結び付けた仕様です。\n- [CommonMark](https://commonmark.org/) — 仕様が必要になった理由、実装が分かれた経緯、保守する人々です。\n- [John GruberのMarkdown](https://daringfireball.net/projects/markdown/) — 最初の説明、設計目標、Perlスクリプトです。\n- [Markdownの構文](https://daringfireball.net/projects/markdown/syntax) — インラインHTMLの規則を含む、Gruber自身の構文説明です。\n- [GitHub Flavored Markdown仕様](https://github.github.com/gfm/) — CommonMarkの上位集合としてのGitHubの方言で、拡張をそれぞれ示します。\n- [RFC 7763：text/markdownメディア型](https://www.rfc-editor.org/rfc/rfc7763) — メディア型、必須の`charset`、`variant`パラメーターです。\n\n\u003chttps://engineer.company/ja/glossary/markdown/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Markdownは、普通のテキストに少数の記号を添えて文書を書く方法です。読みやすさを重視した由来、CommonMarkとGFMの違い、HTMLへの変換、記号がそのまま表示される失敗を説明します。","formats":{"gemtext":"https://engineer.company/ja/glossary/markdown/index.gmi","gopher":"https://engineer.company/ja/glossary/markdown/gophermap","html":"https://engineer.company/ja/glossary/markdown/","json":"https://engineer.company/ja/glossary/markdown/index.json","markdown":"https://engineer.company/ja/glossary/markdown/index.md","pdf":"https://engineer.company/ja/glossary/markdown/index.pdf"},"kind":"page","language":"ja","title":"Markdownとは？","url":"https://engineer.company/ja/glossary/markdown/","version":1}