Markdownとは?文章を書く記法の基本

Markdownは「記号で見た目を指示する」書き方

Markdown(マークダウン)は、テキストファイルの中に決まった記号を書いておくと、見出しや箇条書きとして扱ってもらえる書き方のことです。拡張子は .md がよく使われます。

Wordのようなソフトだと、文字を選んで「見出し1」ボタンを押したり、太字ボタンをクリックしたりしますよね。Markdownはそれを全部キーボードだけで、しかも本文の中に書き込んでしまう方式です。たとえば行の先頭に # を1つ置けば、その行は見出しになります。

例えるなら、原稿用紙に赤ペンで「ここ見出し」「ここ太字」と指示を書き込んでいく感覚に近いです。違うのは、その指示自体がごくシンプルな記号なので、指示を書いたままの状態でもそれなりに読める、という点ですね。# はじめに と書いてあれば、Markdownを知らない人でも「ああ、ここが章タイトルなんだな」と何となく察しがつきます。

よく使う記法

覚えるべき記号は本当に少なくて、最初は次の5つくらいを知っていれば大体なんとかなります。

やりたいこと	書き方
見出し	# 大見出し / ## 中見出し / ### 小見出し
箇条書き	行頭に - とスペース
番号付きリスト	行頭に 1. 2. …
強調(太字)	**強調したい文字**
コード	バッククォートで囲む

# の数が増えるほど見出しのレベルが下がっていく、というのが直感に反して感じるかもしれませんが、HTMLの h1 / h2 / h3 と同じ並びだと思えば馴染みやすいはずです。

なぜエンジニアの周りで多用されるのか

Markdownの文書は、中身がただのテキストです。これが地味に効いてきます。

まず、特別なソフトが要りません。メモ帳でもエディタでも開けるし、10年後に開けなくなる心配もほぼない。次に、テキストなのでGitのようなバージョン管理ツールと相性がいい。「誰がどの行をどう直したか」が1行単位で見えるので、仕様書やREADMEをチームで育てていくのに向いています。

そして、ツール側が読みやすい。見出しがどこで、リストがどこまでか、という構造が記号から機械的に判定できるので、プログラムが文書を解釈しやすいんですね。

Claude Codeとの関わり

Claude Codeを触っていると、Markdownは自然と目に入ってきます。AIへの指示を書いておくファイルや、プロジェクトのREADME、生成されるドキュメントなど、あちこちでこの形式が登場します。

AIへの指示文を書くとき、Markdownの見出しや箇条書きで整理しておくと、内容の区切りがはっきりします。「## コーディング規約」「## 使用ライブラリ」のように章立てしておけば、人間が後から読み返すときにも探しやすい。だらだらと長い一段落にするより、構造を持たせたほうが結果的に扱いやすい文書になります。

最初のうちは「記号を覚えるのが面倒そう」と感じるかもしれませんが、実際に使うのは # と - と ** くらいです。メールやチャットを書くのと同じ感覚で、数日もすれば手が覚えます。

つまずきやすいところ

ありがちなのが、# の後ろにスペースを入れ忘れるパターンです。#見出し と詰めて書くと、環境によっては見出しとして認識されません。# 見出し と半角スペースを1つ挟むのが基本です。

もう一つは、段落を分けたつもりが分かれていないケース。多くの環境では、段落の区切りには空行が必要です。改行しただけでは同じ段落の続きとして扱われることがあります。

あと、Markdownには方言があります。表や取り消し線など、場所によって使えたり使えなかったりする記法が存在します。基本の見出し・リスト・強調あたりはどこでも通じるので、迷ったらそこに寄せておくと安全です。