Markdown: マークダウン見出しの構文と階層のガイドライン
見出しはドキュメントの骨格であり、コンテンツがどのように構成されているかを読者と検索エンジンの両方に伝えます。
1. 学ぶこと
- 両方の Markdown 見出し構文: ATX と Settext
- 6 つの見出しレベルを正しく使用する方法
- 見出し階層のルールとベストプラクティス
- よくある見出しの間違いとその修正方法
- 見出しが SEO とアクセシビリティに与える影響
2. 文書管理者の実際の話
(1) 問題点: 混沌とした見出し階層
Sarah が技術ブログ プロジェクトを引き継いだところ、過去の記事で見出しが無計画に使用されていることがわかりました。いくつかは # を使用し、いくつかは ## を使用し、いくつかはまったく見出しを持たず、他の記事は H2 を完全にスキップして H1 から H3 に直接ジャンプしました。その結果、サイトの目次ジェネレーターは完全に機能しなくなり、読者からはコンテンツが見つからないと苦情が寄せられました。
(2) 解決策: 標準化された見出しルール
Sarah は見出しルールを確立しました。各記事には # 見出しが 1 つだけあり、見出しはレベルをスキップせずに段階的に (## → ### → ####) 進む必要があります。彼女はスクリプトを使用して、50 件の記事すべてを一括で修正しました。修正後、自動生成された目次が再び機能し、読者のページ滞在時間が 40% 増加しました。
3. 2 つの見出し構文
Markdown には 2 つの見出し構文が用意されています。
graph TB
A[Markdown Headings] --> B[ATX Style]
A --> C[Setext Style]
B --> D[# through ######]
B --> E[Most common]
C --> F[=== and ---]
C --> G[H1 and H2 only]
| 構文 | 表記法 | サポートされているレベル | 最適な用途 |
|---|---|---|---|
| ATX | # ～ ###### |
H1 ～ H6 | すべてのシナリオ、最も普遍的 |
| セットテキスト | === / --- |
H1、H2 のみ | ニッチなエディタの好み、互換性が低い |
(1) ATX スタイル (推奨)
ATX スタイルでは、# シンボルの数を使用して見出しレベルを示します。H1 には 1 つの #、H2 には 2 つの ## というようになります。
# Heading Level 1 (H1)
## Heading Level 2 (H2)
### Heading Level 3 (H3)
#### Heading Level 4 (H4)
##### Heading Level 5 (H5)
###### Heading Level 6 (H6)
# の後、見出しテキストの前にスペースが必要です。そうしないと、一部のパーサーがそれを見出しとして認識しません。
(2) セットテキストのスタイル
Settext スタイルは、見出しテキストの下に === または --- を配置します。
Heading Level 1
=======
Heading Level 2
-------
▶ 例: 2 つの見出しスタイルの比較
# ATX Style H1
ATX Style H2
============
Note: the line with === underneath renders as an H1, even though the text says "H2".
4. 見出し階層のガイドライン
(1) 階層を正しく使用する
ドキュメントの見出しには、本の目次のように、明確な階層が必要です。
# Document Title (only one H1)
## Chapter 1 (H2)
### 1.1 Section (H3)
#### 1.1.1 Subsection (H4)
### 1.2 Section (H3)
## Chapter 2 (H2)
H2 → H2 のままで問題ありません。
(2) SEO とアクセシビリティへの影響
見出し階層は SEO とスクリーン リーダーにとって非常に重要です。
| 側面 | おすすめ | 避ける |
|---|---|---|
| H1 カウント | 1 ページに 1 つ | 複数の H1 が検索エンジンを混乱させる |
| キーワード | H1 には主要な用語が含まれ、H2 には関連用語が含まれています。キーワードの詰め込み | |
| 階層 | ステップバイステップ、レベルスキップなし | カオスな H1→H3→H2 ジャンプ |
| 長さ | H1 ≤ 60 文字、H2 ≤ 40 文字 | 段落全体を見出しとして |
▶ 例: 正しい見出し階層と間違った見出し階層
✅ Correct:
# CSS Layout Tutorial
## Flexbox
### Flex Container Properties
### Flex Item Properties
## Grid
### Grid Container Properties
❌ Incorrect:
# CSS Layout Tutorial
### Flex Container Properties (skipped H2)
## Flexbox
#### Flexbox Properties in Depth (H3→H4 awkward jump)
## Grid
5. 見出しの書式設定と特殊文字
(1) 見出しには太字、斜体、コードを使用できます
## Installing Dependencies With `npm install`
## Understanding **flex-grow**, **flex-shrink**, and **flex-basis**
## What Is *Responsive Design*?
(2) 過度に長い見出しコンテンツを避ける
❌ Avoid:
## A Detailed Tutorial on How to Use Python's requests Library to Send HTTP Requests
✅ Recommended:
## Sending HTTP Requests With the requests Library
▶ 例: 見出しの最適化の前後
❌ Too long:
## This Article Will Teach You How to Set Up a Python Development Environment in VS Code on Windows
✅ Optimized:
## Setting Up Python in VS Code
6. 完全な例: 記事の見出し構造
# Data Analysis With Python
## 1. Data Preparation
### (1) Importing Libraries
### (2) Reading Data
### ▶ Example: Reading a CSV File
## 2. Data Cleaning
### (1) Handling Missing Values
### ▶ Example: Filling Null Values
### (2) Removing Duplicates
## 3. Data Visualization
### (1) Line Charts
### ▶ Example: Plotting a Trend Chart
### (2) Bar Charts
期待される結果: 読者と検索エンジンの両方がすぐに理解できる、明確に階層化された文書構造。
❓ よくある質問
# と見出しテキストの間にスペースは必要ですか?#Title は見出しとして認識されず、プレーン テキストとして扱われます。 # Title が正しい方法です。{#custom-id} のように見出しの後にカスタム ID を追加します。📖 まとめ
- 2 つの見出し構文: ATX (
#) および Settext (===)。全体を通して ATX の使用を推奨します #の後には必ずスペースを入れてください。そうしないと見出しとして認識されません。- ページごとに 1 つの H1、レベルをスキップせずに段階的に進みます
- 見出しは短くしてください (H1 ≤ 60 文字)。キーワードの詰め込みを避ける
- 見出しにはコード、太字、斜体、その他の書式を含めることができます
- 適切な見出し階層は、読者と検索エンジンの両方に役立ちます
📝 練習問題
-
初心者: H1、H2、および H3 の見出しを持つ短い Markdown 作品を書きます (読書ノートまたは学習計画など、トピックを自分で選択します)。各見出しレベルに、その上のレベルよりも
#が 1 つだけ多いことを確認してください。 -
中級: 最近作成した文書を開き、その見出し階層がルールに従っているかどうかを確認します。レベルのスキップや混乱がある場合は、修正してください。次に、H1 がいくつあるか数えます (正解は 1)。
-
課題: VS Code の Markdown All in One 拡張機能を使用して目次を生成し (
[TOC]と入力するか、コマンドを使用)、見出し階層が正しいことを確認します。生成された目次が正しくない場合は、見出しレベルを調整する必要があります。
