Markdownの見出し

見出しは文書の骨格です。Markdownでは1文字で足ります。行の頭に # を置き、段階の数だけ繰り返すだけ。あとに続くもの、つまり示される構造も、生成される目次も、作られるアンカーリンクも、段階さえ正しければ勝手についてきます。

下の # の数を変えて、大きさが動くのを見てください。

# 文書のタイトル

導入の文章。

## 大きな節

### 小さな節

#### さらに細かい項目

見出しの下にある文章は、その見出しに属します。

6つの段階

# から ###### が <h1> から <h6> に対応します。7段階目はありません。7つめの # はそのまま文字として表示されます。

# 見出し1
## 見出し2
### 見出し3
#### 見出し4
##### 見出し5
###### 見出し6

実際に使うのは3つまででしょう。##### まで届く文書は、たいてい2つに分かれたがっている文書です。

空白は省略できません

#見出し は、シャープで始まるただの段落です。# 見出し が見出しです。最後の # のあとには必ず空白を置いてください。

見出しが素の文章として出てしまう理由は、圧倒的にこれが多く、しかもプレビューを見るまで気づけません。

1文書に # はひとつ

# はひとつだけ使い、それを文書のタイトルとして扱います。その下は ## と ### で組み立てます。

理由は2つあり、検索エンジンの話はそのうち1つだけです。

• 読者とスクリーンリーダーにとって、見出しの段階はたどれる目次です。# からいきなり ### へ飛んだり、# の見出しが3つあったりすると、その目次は意味を失います。
• 検索エンジンにとって、<h1> はページが何についてのものかを示す強い手がかりです。複数あると薄まります。

下りるときも段階を飛ばさないでください。### は ## の下にあるべきで、# の直下ではありません。

Setext形式の見出し

何年も前に書かれたファイルで出会う、古い記法があります。文字を = や - で下線のように囲むものです。

文書のタイトル
==============

大きな節
--------

= が <h1>、- が <h2> になります。できるのはそれだけで、だから廃れました。3段階目を表現する手がないのです。見かけたら分かるようにしておいて、自分では # を書いてください。

落とし穴に注意。段落のすぐ下にハイフンの行を置くと、水平線ではなく、その段落が見出しになります。区切り線が欲しいなら、上に空行を入れてください。

見出しはアンカーリンクになります

たいていの処理系 — GitHub、静的サイトジェネレータ、ドキュメントツール — は、見出しのテキストから id を作ります。おかげで節に直接リンクできます。

[アンカーリンクの節](#見出しはアンカーリンクになります)を見てください。

規則はほぼ共通です。テキストを小文字にし、空白をハイフンに置き換え、句読点を落とす。## The Six Levels なら #the-six-levels になります。日本語の見出しはそのまま残るので、URLの中では percent エンコードされた形になります。同じ文字の見出しが2つあると、たいてい後ろのほうに -1 が付きます。

目次が成り立つのはこれのおかげで、このページの目次もそうです。リンクについてはリンクのガイドに詳しく書いてあります。

よくある間違い

# のあとに空白がない。 その行は段落として出ます。見出しが出てこないときは、まずここを見てください。

見出しの前後に空行がない。 処理系によっては、特に段落の直後の見出しの前に空行を求めます。上下に1行ずつ入れておけば、どこでも通ります。

行末のシャープ。 ## 節 ## は文法上は正しく、閉じるシャープは取り除かれますが、雑音です。付けないでください。

見出しの代わりに太字。 1行だけの **節のタイトル** は見出しに見えますが、見出しではありません。目次に載らず、アンカーもできず、構造も生みません。スクリーンリーダーはそれをたどれず、検索エンジンも節としては読みません。

1ファイルに # が複数。 文書を分けるか、最初のひとつを残して段階を下げてください。

よくある質問

Markdownの見出しは何段階ありますか？

6段階です。<h1> にあたる # から <h6> にあたる ###### まで。7つめの # は見出しではなく、そのまま文字になります。たいていの文書は3段階あれば足ります。

見出しが効かないのはなぜですか？

ほぼ必ず、# と文字のあいだの空白が抜けています。#タイトル は段落、# タイトル が見出しです。2番目に多いのは、直前の段落と見出しのあいだに空行がないことです。

1つの文書にH1はひとつだけにすべきですか？

原則として、はい。# ひとつが文書のタイトルとしてはたらき、残りは ## と ### でその下に入ります。スクリーンリーダーにとって目次が意味を保ち、検索エンジンにとってページの主題が曖昧にならずにすみます。

見出しへリンクするには？

生成されたアンカーを使います。テキストを小文字にし、空白をハイフンに、句読点を削って、# を頭に付けてリンクします。## Getting Started なら [移動](#getting-started) です。細かい規則は処理系によって少し違います。

# の見出しと下線式の見出しは何が違いますか？

最初の2段階については、結果は同じです。行の下の = が <h1>、- が <h2> になります。この古いSetext形式は3段階目から6段階目を表現できないので、# の記法がほぼどこでも取って代わりました。