見出しID
見出しIDは、Markdownの拡張機能で、見出しにカスタム識別子を追加し、正確なリンクの作成とドキュメント構造の制御を容易にします。
基本的な構文
見出しIDの追加
見出しIDは、中括弧構文を使用し、見出しテキストの後に配置します:
## 私の見出し {#カスタムID}
レンダリング効果:
HTMLの出力は、見出し要素にこのカスタムIDを追加します:
<h2 id="カスタムID">私の見出し</h2>
複数レベルの見出しID
すべてのレベルの見出しにカスタムIDを追加できます:
# 第1レベル見出し {#第1レベル}
## 第2レベル見出し {#第2レベル}
### 第3レベル見出し {#第3レベル}
#### 第4レベル見出し {#第4レベル}
適用シナリオ
アンカーリンクの作成
カスタムIDを使用して、文書内の特定の部分を指すリンクを作成できます:
[クリックして見出しにジャンプ](#カスタムID)
...他のコンテンツ...
## 私の見出し {#カスタムID}
レンダリング効果:
リンクをクリックすると、カスタムID
を持つ見出しに直接ジャンプします。
外部文書の特定セクションへのリンク
カスタムIDは、外部文書の特定のコンテンツへのリンクも容易にします:
[他の文書の特定セクションへのリンク](other-doc.html#特定セクション)
URLを介した特定セクションの共有
IDを持つ見出しは、文書の特定のセクションを指すURLを介して共有できます:
https://www.markdownlang.com/documentation.html#インストールガイド
高度な使用法
複数単語の見出しID
見出しに複数の単語が含まれる場合、見出しIDは通常、ハイフンで接続します:
## インストールと設定ガイド {#インストールと設定}
目次生成と見出しID
多くのMarkdownプロセッサは、見出しの内容に基づいて自動的にIDを生成します。カスタムIDを使用することで、目次のリンクが見出しの内容の変更の影響を受けないようにできます:
## はじめにガイド {#はじめに}
後で見出しを「はじめに」に変更しても、IDが同じままであるため、リンクは有効です。
国際化と非英語文字
非英語の見出しの場合、カスタムIDは特に有用で、安定した英語の識別子を提供します:
## インストール手順 {#installation}
## 使用ガイド {#usage}
## よくある質問 {#faq}
互換性と実装の違い
さまざまなプラットフォームでのサポート状況
プラットフォーム/ツール | 見出しIDサポート | 構文 |
---|---|---|
GitHub Markdown | ✅ | {#id} |
GitLab Markdown | ✅ | {#id} |
Jekyll (kramdown) | ✅ | {:#id} または {#id} |
Hugo | ✅ | {#id} |
CommonMark | ❌ | サポートされていません |
VitePress | ✅ | {#id} |
Pandoc | ✅ | {#id} |
自動ID生成ルール
カスタムIDが提供されない場合、ほとんどのMarkdownプロセッサは見出しテキストから自動的にIDを生成します:
- 小文字に変換
- 特殊文字を削除または置換
- スペースをハイフンに置換
- 重複するハイフンを削除
- IDの一意性を確保(通常、数値接尾辞を追加)
例:
見出し | 自動生成ID |
---|---|
## はじめに | #はじめに |
## FAQ & ヘルプ | #faq-ヘルプ |
## クイックスタート | #クイックスタート または #セクション-1 (プラットフォームによって異なる) |
ベストプラクティス
見出しID命名規則
✅ 推奨プラクティス:
1. **簡潔で説明的なIDを使用**:
- `{#インストール}`
- `{#api-リファレンス}`
- `{#トラブルシューティング}`
2. **一貫した命名スタイルを維持**:
- すべて小文字
- 単語の区切りにハイフンを使用
- アンダースコアやキャメルケースを避ける
3. **IDの安定性を維持**:
- 頻繁なID変更を避ける
- 見出しテキストを変更する際に元のIDを保持
❌ 避けるべき慣行:
1. 特殊文字の使用(`!@#$%^&*()`など)
2. 説明的でないID(`{#セクション1}`など)の使用
3. 過度に長いIDの作成
4. スペースや句読点の使用
文書構造と見出しID
大きな文書の場合、ナビゲーションを容易にするために、主要な章に標準化されたIDを使用することをお勧めします:
# 製品ドキュメント {#製品ドキュメント}
## はじめに {#はじめに}
## インストール {#インストール}
### Windows インストール {#インストール-windows}
### macOS インストール {#インストール-macos}
### Linux インストール {#インストール-linux}
## 設定 {#設定}
## APIリファレンス {#apiリファレンス}
## よくある質問 {#faq}
実践的な応用例
技術文書での見出しID
技術文書の見出しIDは、ユーザーが特定のセクションに直接リンクするのに役立ちます:
# API ドキュメント {#api-ドキュメント}
## 認証 {#認証}
### APIキーの取得 {#api-キー取得}
### OAuth認証 {#oauth}
## エンドポイント {#エンドポイント}
### ユーザーエンドポイント {#エンドポイント-ユーザー}
### 製品エンドポイント {#エンドポイント-製品}
学術論文での見出しID
学術論文は、見出しIDを使用して引用と相互参照を作成できます:
# 研究方法論 {#方法論}
[研究結果](#結果)に示すように、私たちの方法は複数のテストケースで優れた性能を発揮します。
...
# 研究結果 {#結果}
このセクションでは、[研究方法論](#方法論)で説明した実験結果を示します。
一般的な問題の解決
見出しIDが機能しない
見出しIDが機能しない場合:
- プラットフォームがカスタム見出しIDをサポートしているかを確認
- 構文が正しいことを確認(通常は
{#id}
) - IDに無効な文字が含まれていないことを確認
- 別のMarkdownプロセッサを試す
ID競合
同じ文書内に同一のIDが複数ある場合、予測できないリンク動作を引き起こす可能性があります:
## 問題 {#問題} <!-- 最初のID -->
...