Markdownの書き方｜見出し・リンク・表と表示確認の基本

※本記事にはPRを含む場合があります。

こんにちは。『脱会社員』脱サラを応援し続けるブログ、運営者の『なかびー』です。

Markdownを使うと、普通のテキストに少し記号を添えて、見出し・リスト・リンク・コードなどの構造を表せます。ただし、同じ文章を別の場所へ貼り付けたとき、改行や表の見え方が変わることがあります。記号の暗記だけでなく、「どの記法を、どの表示先で使うか」を確かめることが、読みやすい文書を作る近道です。

この記事では、架空の「読書メモ整理ノート」のREADMEを一つ作ります。見出し、段落、箇条書き、順序付き手順、コード、相対リンク、表、タスクリストを順に確認し、崩れたときの直し方まで練習します。GitHubのアカウント作成やリポジトリ操作ではなく、プレーンテキストの記法と表示先の違いに集中します。

確認日は2026年10月4日です。基準としてCommonMark 0.31.2とGitHub Flavored Markdown、以下GFMの公式仕様を参照しました。掲載READMEはmarkdown-it-py 4.2.0でCommonMarkプリセットと部分拡張を比較し、生成HTMLの構造を検証しています。部分拡張は表・取り消し線・タスクリストを有効にしたもので、GitHubの全機能や実画面を再現したものではありません。実ブラウザー、GitHub、各エディターの表示・操作は未検証なので、最後は使う場所で確認してください。

Markdownの基本は、文章の構造と表示先を分けて考えること

Markdownの記号は見た目を直接指定するものではない

Markdownでは、行頭の#で見出し、行頭の-でリストなど、文章の役割を表します。何ポイントの文字で、どの色で、何px空けるかという細かい見た目は、表示するアプリやサイト側のスタイルに依存します。あるサービスで見出しが大きかったからといって、別の場所でも同じ大きさになるとは限りません。

そのため、見出しを大きく見せたいから階層を飛ばす、本文を太字だらけにする、といった使い方より、文書の意味に沿って構造を付けることを優先します。大きな項目の下に小さな項目を置く、順番が必要な手順だけ番号を付ける、コマンドはコードとして示す。このように書くと、表示先が変わっても文書の意図が伝わりやすくなります。

保存されるファイルは通常のテキストです。拡張子は.mdがよく使われますが、拡張子を変えるだけで文書の内容が正しくなるわけではありません。文字コードやファイル名も受け取り先に合わせます。今回はUTF-8でREADME.mdとして保存し、テキストの編集画面とプレビューを切り替えて確認する進め方を想定します。

CommonMarkとGFMを同じものとして扱わない

Markdownには複数の処理系や拡張があります。CommonMarkは記法の解釈を明確にする仕様で、見出し、リスト、リンク、コードなどの基礎を確認する基準になります。GFMはCommonMarkをもとに、表やタスクリストなどを加えた仕様です。表が書ける場所の例を見て、どのMarkdownでも同じ表が使えると思い込まないようにします。

さらに、GFMの仕様とGitHubというサービスの表示処理も完全に同じ範囲ではありません。サービス側ではHTMLの安全処理、見出しへのリンク、参照の自動変換などが加わる場合があります。エディターのプラグインで似た見た目になっても、GitHubとすべて同じ動作だと保証するものではありません。使う場所の公式説明を先に確認しましょう。

※表は横にスクロールできます。

本記事では、基本記法と拡張を同じREADMEに入れ、どこが変わるかを観察します。表やチェック欄を使えない環境へ渡す場合は、箇条書きや「完了・未完了」という文章へ置き換えられます。見栄えのよい機能を増やすことより、受け取り側で内容を読めることを完成条件にしましょう。

見出しは半角記号と空白で書く

ATX形式の見出しは、行頭の半角#と、その後の半角空白を使って書きます。#が一つなら最上位、##ならその下、###ならさらに下の階層です。CommonMarkでは一つから六つまでの#が見出しの形式に使われます。#見出しのように空白を入れない形は、通常の見出しとして解釈されないため注意してください。

一つのREADMEでは、文書名に#を一つ、その下の主要項目に##を使う構成が読みやすい出発点です。これは分かりやすい編集方針で、文書内の最上位見出しを複数書くこと自体が常に構文エラーという意味ではありません。ページに既存のタイトルが付くサービスでは、その表示構造も見ながら適切な階層を選びます。

# 文書の題名

## 使い方

本文を書きます。

### 補足の手順

必要な説明を書きます。

見出しの前後に空行を置くと、編集画面でも構造を追いやすくなります。処理系の条件によって空行が必須でない場面もありますが、読みやすさのために区切る書き方をそろえると安心です。太字の行を見出しの代わりに並べるより、見出しの構造を使った方が目次や文書の移動にも役立ちます。

段落、見た目の折り返し、改行を区別する

長い文章がエディターの幅で折り返されることと、ファイルに改行文字が入っていることは別です。さらに、ファイル内で一回改行したからといって、表示先でも必ず強制改行になるとは限りません。CommonMarkの通常の一改行はsoft line breakで、段落の中の続きとして扱われる表示があります。

段落を分けたいときは空行を入れます。同じ段落の中で改行を明示したい場合は、行末の半角空白二つ以上や、行末のバックスラッシュなどの書き方があります。ただし、行末空白はエディターの自動整形で消えることがあるので、用途に応じて選び、表示結果を確かめてください。GitHubでもREADMEとコメントなどで改行の扱いが異なる場面があるため、貼り付け先の説明を確認します。

架空READMEを一つ作り、リスト・リンク・コードを練習する

先に読者と完成条件を決める

ここで作るREADMEは、架空の読書メモを整理する手順書です。実在するアプリの機能紹介や、自分が開発したという実績ではありません。読む人が「何の文書か」「何を書けばよいか」「保存前に何を確かめるか」を理解できることを目標にします。見出しだけ整っていて中身の手順が足りない文書にしないよう、目的と必要項目を先に決めます。

新しい練習用フォルダーを用意し、その直下にREADME.md、下位のdocsフォルダーにrules.mdを置きます。既存ファイルの上書きは避け、同名がある場合は別の練習フォルダーを使います。相対リンクを確かめるため、二つのファイルの位置関係を保ってください。PCの個人名を含む絶対パスや会社の内部URLを、例のリンク先へ入れる必要はありません。

完成見本のREADMEを書く

次がREADME.mdの全文です。コード例の中にさらに三つのバッククォートがありますが、ここではREADMEの記法として表示しています。保存するときは内容をテキストとしてコピーし、不要な説明行を混ぜないでください。表とタスクリストは拡張要素なので、基本記法だけのプレビューでは見え方が変わります。

# 読書メモ整理ノート

読んだ本のメモを、あとから探しやすくするための**架空の練習用説明書**です。
実在するアプリの操作手順ではありません。

この文書では、入力例と確認項目を一か所にまとめます。

## できること

- 本の題名と読んだページを記録する
- 気になった一文について、自分の言葉でメモする

## 使い方

1. 新しいメモを用意する
2. 題名とページを書く
   - ページが不明なら「不明」と書く
3. 保存する前に読み直す

## 入力例

`book-title`は、本の題名を表す項目名です。

```text
book-title: 架空の本A
page: 12
note: 仕組みを自分の言葉で説明する
```

## 保存のルール

詳しい方針は[保存ルール](docs/rules.md)を確認します。
記法の基準は[CommonMarkの仕様][commonmark]です。

[commonmark]: https://spec.commonmark.org/0.31.2/

## 確認表

| 項目 | 例 | 必須 |
| --- | --- | :---: |
| 題名 | 架空の本A | はい |
| ページ | 12 | いいえ |
| メモ | A\|Bの比較 | はい |

## 実施チェック

- [x] 題名を書く
- [ ] ページを確認する
- [ ] 保存先を確認する

## 注意

> この例は学習用です。実在する個人情報は書きません。

記号そのものを書く例：\*強調にしない\*。

docs/rules.mdには、次の短い内容を保存します。READMEから見た相対パスがdocs/rules.mdなので、フォルダー名とファイル名の大文字小文字もそろえます。環境によっては大文字小文字の違いが見逃され、別の環境へ移した後にリンク切れになることがあります。

# 保存ルール

練習用のメモは、新しい名前で保存します。

- 既存ファイルを上書きしない
- 個人情報や秘密情報を書かない

完成見本には最上位の見出しが一つ、その下の見出しが七つあります。コードブロックは一つで、入力例を表示するだけです。表は三列・データ三行、タスクリストは三項目で最初だけ完了です。リンクは保存ルールへの相対リンクと、CommonMark仕様への外部リンクの二つです。この数を先に把握しておくと、変換後の欠落や意図しない分割を見つけやすくなります。

箇条書きと番号付き手順を使い分ける

順序のない項目には-、手順には1.、2.、3.のような番号を使います。記号の後ろには空白を入れます。番号付きリストは、処理系が連続した番号を表示する場合があるため、ソースに同じ数字を書いても見た目だけ整うことがあります。それに頼り過ぎず、編集時にも手順の順番が分かるように書いておくと見直しやすくなります。

READMEでは二番目の手順の下に、「ページが不明なら不明と書く」という箇条書きを入れています。子の項目が、親の2.の後に続く本文の位置に合うように空白で字下げしています。何文字でもよいわけではなく、親の記号や空白幅によって解釈が変わるため、意図どおり二番目の手順に所属しているかをプレビューで確認してください。

タブと空白が混在すると字下げが見た目と違うことがあります。エディターで空白文字を表示できるなら、崩れた行だけでも確認すると原因を見つけやすくなります。リスト内に段落やコードを置く場合も、所属を示す字下げが必要です。最初は深い入れ子を避け、一段の子項目で関係を確かめるとよいでしょう。

リンク文字列とリンク先を別々に点検する

リンクは、[読む人に見せる文字](リンク先)という形です。「こちら」だけより、「保存ルール」のように行き先が分かる文字を使うと、本文の中で目的を理解しやすくなります。リンクの表示名が正しくても、URLが別の場所を指していることがあるので、名前と実際の参照先を別々に確認してください。

READMEには参照形式のリンクも入れています。[CommonMarkの仕様][commonmark]と書き、別の行で[commonmark]: URLを定義する形式です。同じ参照先を繰り返す文書でURLをまとめられますが、定義名のつづり違いや定義漏れに注意します。参照定義の行は、通常、本文の独立した段落としては表示されません。

相対リンクは、文書の位置からの関係で決まります。READMEとdocsフォルダーを一緒に渡せば関係を保てますが、READMEだけを別の場所へ移すとリンク切れになります。チャットへ本文だけ貼り付ける場合も、そのチャットが同じフォルダーを参照できるとは限りません。渡し方に応じて、相対リンクを使うか、権限のある共有先へ置くかを判断します。

コード・表・タスクリストと、拡張の境界を確認する

コードとして見せると、記号をそのまま読める

文章中の短い項目名やコマンドは、バッククォートで囲むインラインコードにします。READMEのbook-titleは項目名として区別できます。複数行のコードや入力例は、同じ種類の記号を三つ以上並べたフェンスで囲みます。開始行の後ろにtextやpythonなどの言語名を置く書き方がありますが、色分けの対応は表示先に依存します。

言語名を付けたからコードが実行されるわけではありません。通常のMarkdown文書では表示上の情報です。ただし、Notebookや独自の実行機能が付いたサービスには別の仕組みがあるため、読者へ実行を求める場合は、その環境と操作を明記します。コマンドを載せるときは、コピー後に何が起きるかも説明し、危険な削除や秘密情報の入力を無説明で混ぜないようにします。

コードブロックの終了記号を忘れると、その後の見出しや本文もコードの一部として扱われる場合があります。表示が途中からすべて等幅文字になったときは、装飾設定を探す前に、開始と終了のフェンスを数えます。開始にバッククォートを使ったなら終了も同じ種類で、必要な長さ以上にします。チルダのフェンスと混ぜないでください。

バッククォートそのものを見せたいとき

コード内にバッククォートがある場合は、外側の区切りを長くする方法があります。例えばaとbの間に一つのバッククォートを含めたいなら、外側を二つで囲みます。三つのフェンスを含むMarkdown見本全体を表示したいなら、外側を四つにすると区別できます。単に同じ長さで重ねると、意図しない場所で閉じる場合があります。

``a`b``

````markdown
```text
ここに入力例を書く
```
````

この例は「バッククォートを含む記法を表示するための書き方」です。内側の三つの記号まで見せたい場面に使います。通常の短いコードなら、三つで囲む基本形だけで十分です。長さを増やす必要があるかは、表示したい内容の中に同じ記号列が含まれているかで判断しましょう。

文章中のアスタリスクを強調にしたくない場合は、\*のようにバックスラッシュで打ち消す方法があります。READMEの「\*強調にしない\*」は、表示後にアスタリスク自体が残る例です。コードブロックの中では記号をそのまま示せるので、むやみにエスケープを増やす必要はありません。文章の中か、コードの中かを先に分けます。

表はヘッダーと区切り行をセットにする

GFMの表では、列を縦棒で区切り、ヘッダーの次にハイフンの区切り行を置きます。READMEでは項目・例・必須の三列を作り、必須列の区切りにコロンを付けて中央寄せを指定しています。表の前後には空行を置き、文章やリストと混ざらないようにします。表の具体的な書き方はGitHub公式の表ガイドで確認できます。

セル内に縦棒を表示したい場合は、区切りと区別する必要があります。READMEではAとBの比較を書くセルにバックスラッシュ付きの縦棒を使いました。拡張対応の変換結果では、三列を保ったままセル内にA|Bの比較と表示されることを検証しています。縦棒をそのまま置くと、意図せず列が増えたように見える原因になります。

Markdownの表は、長文、複雑な結合セル、何段もの見出しを表すのに向かない場合があります。セルへ無理に改行やHTMLを入れて整えるより、短い比較に絞り、詳細を表の下の文章へ分けると読みやすくなります。スマートフォンで横に長くなる場合も、表示先がスクロールを用意してくれるとは限らないため、実際の幅で確認します。

チェック欄と取り消し線は対応する場所で使う

タスクリストは、箇条書きの記号の後に[ ]または[x]を付ける形です。READMEでは題名を書く項目だけ完了にしています。対応する処理系ではチェック欄として表示されますが、基本的なMarkdownだけでは角かっこ付きの文字として残る場合があります。クリックで変更できるか、変更が文書へ保存されるかは、表示サービスや権限によって別途確認が必要です。

取り消し線も拡張に含まれる記法です。GFMではチルダによる取り消し線が使えますが、受け取り先が対応しない場合は記号のまま表示される可能性があります。重要な修正を取り消し線だけで表すと意味が失われやすいので、「旧案」「変更後」などの言葉も付けると安心です。見た目の装飾に判断情報をすべて預けないようにしましょう。

※表は横にスクロールできます。

この比較は、同じテキストを自前の二つの設定でHTMLへ変換した結果です。GitHubの実画面を見比べた記録ではありません。タスクリストの拡張にはmdit-py-plugins 0.6.1を使い、生成されたinputはdisabledでした。使うサービスでも必ず無効なチェック欄になる、という意味ではなく、試した処理系の範囲を示しています。

表示が崩れたら、空行・字下げ・区切りから直す

一度に全部変えず、最小の例へ戻す

文書が崩れたときに、すべての空白を削除したり、適当なHTMLを足したりすると原因が分かりにくくなります。問題の前後数行を別の練習ファイルへコピーし、見出しだけ、リストだけ、表だけという小さな形で確認します。前のコードフェンスが閉じていないために後ろの見出しが崩れるなど、原因が一つ前の段落にあることもあります。

まずソースの記号、次に生成された構造、最後に見た目の順で調べます。記法として表が生成されていないのか、表はあるが横幅のスタイルで読みにくいのかでは、直す場所が違います。プレビューのテーマを変えるだけでは、列の区切りや空白の誤りは直りません。表示先の仕様と自分の文章を切り分けましょう。

一改行・空行・強制改行を比較する

次の三つは見た目が似ていますが、意味が違います。一つ目は同じ段落内の通常の改行、二つ目は空行で分けた段落、三つ目は行末のバックスラッシュで改行を明示した例です。コピーするときはバックスラッシュを行の途中へ移さず、その直後で改行します。

一行目
二行目

一段落目

二段落目

強制改行の一行目\
強制改行の二行目

変換テストでは、通常の一改行だけの小例は一つのp要素のまま、空行を入れた小例は二つのp要素、行末バックスラッシュの小例はbr要素が生成されました。行末の半角空白二つでもbrが生成されることを別に確認しています。ただし、ここから文字の大きさや行間まで同じだとは言えません。実際の表示はアプリのスタイルも見ます。

住所や短い詩のように同じ段落で改行が必要な場合と、話題が変わる段落とを区別して使いましょう。すべての行に強制改行を付けると、画面幅が変わった際に不自然な折り返しになることがあります。文書の意味に合った段落を作り、表示幅による自然な折り返しは表示側に任せる方が扱いやすい場面もあります。

よくある崩れ方から原因を探す

※表は横にスクロールできます。

表やリストの中でコードを見せる場合は、複数の記法が重なります。最初から複雑な入れ子へ進まず、コードを表の外へ出す、長い説明を別段落へ移すといった構造の見直しも有効です。「記号を増やして何とか整える」以外に、文書を簡単にするという選択肢があります。

構文エラーという明確な停止が出ず、普通の文字として表示されることもMarkdownの特徴です。変換に成功したという表示だけでは、意図した見出しや表になったか分かりません。重要な構造は、見出しの数、表の列数、手順の所属、コードの範囲など、確認項目を持って点検します。

HTMLを足す前に、許可範囲と安全性を確認する

Markdownには生のHTMLを扱う仕様や処理系がありますが、表示サービスによって許可・除去・エスケープの方針が違います。あるローカルプレビューで使えたタグが、共有先でも同じように表示されるとは限りません。JavaScriptや危険な属性などは制限されることがあり、制限を回避する前提で文書を作るべきではありません。

本記事の変換試験ではhtml=Falseに設定し、生HTMLをタグとして実行・表示するのではなく文字として逃がしています。小さなscriptタグの文字列も、生成HTMLに実行可能なscript要素が入らないことを確認しました。これは試験した設定の確認であり、あらゆるMarkdownの安全性を保証するものではありません。第三者から受け取ったMarkdownをサイトへ組み込む場合は、利用する処理系の安全設定も確認します。

レイアウト目的でHTMLを大量に混ぜると、Markdownとしての移植性や編集しやすさが下がります。必要なら対象サービスで許可された形式を選び、使えない環境向けの代替も用意します。単純な見出し、段落、リストで表現できる内容なら、まずその基本構造を整える方が後の手間を減らせます。

共有前にリンク・画像・内容を点検し、再現できる形で残す

画像には意味のある代替テキストを付ける

画像を入れる記法は、リンクの前に!を付けた形です。例えば、自分が権利を持つ表紙画像をimages/cover.pngへ用意したなら、次のように書けます。この行は画像の指定例であり、今回のREADMEに画像ファイルを自動で追加するものではありません。ファイルが存在しなければ、記法が正しくても表示されません。

![読書メモ整理ノートの表紙](images/cover.png)

角かっこの中は代替テキストです。画像が見えない状況でも意味を補えるよう、その画像が何を伝えるかを自然な文章で書きます。「画像」「スクリーンショット」だけでは内容が伝わりにくいので、対象や役割を具体的にします。文字情報を画像の中だけに閉じ込めず、重要な手順や数値は本文にも記載してください。

画像を外部URLで読み込む場合、表示時にその配布元へアクセスが発生することがあります。第三者の画像や追跡用URLを、確認せず文書へ貼り付けないようにします。ローカル画像を共有する場合も、ファイル一式が相手に届くか、画像内に個人情報や権限のない資料が映っていないか、利用条件を満たしているかを確認します。見えているから自由に再配布できるとは限りません。

共有先での確認は、ローカルプレビューと別に行う

ローカルのプレビューで整ったら、実際に使う場所でも確認します。Markdown対応のコメント欄、README、ドキュメントサービスなど、貼り付け先が同じ処理系とは限りません。下書きやプレビューで確認できるなら、公開前にそこを使います。確認のためだけに公開リポジトリや第三者のオンライン変換サイトへ秘密の文書を送る必要はありません。

ブラウザーの幅を狭めたときの表、長いURLの折り返し、コードの横方向、見出しの移動、リンク先へのアクセスを確認します。自分はログインしているので開けても、受け取り側には権限がない資料もあります。共有する相手に必要なアクセスがあるかを確認し、権限を広げる必要がある場合は、許可された範囲で調整します。

今回の検証では、二条件でのHTML変換と構造を確認しました。最上位見出し1・下位7、表対応時のヘッダー3・本文9セル、タスク3・完了1、コード範囲、エスケープした縦棒、相対リンク先の実在を照合しています。画面での配色、横スクロール、キーボード操作、読み上げ、GitHubへの保存後表示は確認していないため、実際の利用先で別途点検します。

完成チェックを短い一覧にする

※表は横にスクロールできます。

同じREADMEを後から直すときも、この一覧を使えます。見出しを追加したら目次や内部リンク、表に列を増やしたらスマートフォン幅、ファイルを移動したら相対リンク、コード例を変えたらフェンスと実行説明を見直します。文章の修正だけで表示上の問題が起きることもあるので、最後にプレビューする工程を残しておきましょう。

複数人で編集する場合は、見出しの付け方、改行、リストの字下げ、表を使う範囲、対応するMarkdown処理系を簡単に共有します。細かい見た目の好みを増やすより、読み手が迷わないルールに絞ります。自動整形を使う場合は、行末空白や入れ子が変わっても意味が保たれるか確認してから運用します。

仕様と未確認範囲を一緒に引き継ぐ

READMEを渡すときは、.mdファイルだけでなく、必要な相対リンク先や画像もそろえます。表示に特定の拡張が必要なら、その名前と代替表現を記載します。「Markdownだからどこでも同じ」と書くより、「表とタスクリストに対応した表示先を想定」と具体的に伝える方が、受け取り側が確認しやすくなります。

プログラミング作品のREADMEに応用するなら、記法を整えるだけでなく、目的、動作条件、使い方、制約、検証した範囲を入れます。書く内容の組み立てはプログラミングのポートフォリオの作り方も参考になります。文章とコードを一緒にレビューしてもらう学習方法を検討する場合は、必要な支援を整理し、副業向けプログラミングスクールの比較で質問対応や成果物支援の範囲を確認してください。

今回の小例では、普通の文章から読みやすいREADMEを作り、基本記法と拡張の差を確かめました。次は自分の手順書を短く書き、見出し、リスト、コード、リンクだけで意味が伝わるかを見直してみましょう。必要になってから表や拡張を足していくと、対応先に合わせて直しやすい文書になります。

仕様の参照先は、CommonMark 0.31.2、GFM仕様、GitHubの基本記法ガイド、markdown-it-pyの設定資料です。文書の意図と記法、処理系の設定、実際の表示を分けて確認することが、Markdownを安全に使い続ける基本になります。