Markdownコールアウトガイド
コールアウトとは?
基本的なMarkdownでは単純な引用文(>
)のみが提供されますが、GitHubが改良されたデザインを導入したことで、執筆者が読者に特定の内容を強調し、意図を明確に伝えることができるコールアウト機能を提供するようになりました。この機能はGitLabやObsidianなど、他のMarkdownレンダリングツールでも採用され、広く使用されています。
基本引用文の文法:
> これは基本的なMarkdown引用文です。
> 単純な灰色の縦線とインデントのみが提供されます。
レンダリング結果:
これは基本的なMarkdown引用文です。 単純な灰色の縦線とインデントのみが提供されます。
一方、コールアウトは色、アイコン、タイトルなど豊富な視覚的要素を提供し、内容の性格を明確に伝えることができます。
基本的な使用法
コールアウトは以下のような文法で使用します:
> [!タイプ]
> コールアウトの内容
[!tip] 大文字・小文字の規則
コールアウトのタイプは大文字・小文字を区別しません。[!NOTE]
、[!note]
、[!Note]
はすべて同様に動作します。
ただし、一貫性のために一つのルールを決めて使用することをお勧めします:
- 小文字(
[!note]
):タイピングが楽で速い(Shiftキー不要) - 大文字(
[!NOTE]
):視覚的に目立ちやすく、公式的な印象
推奨事項:小文字の使用をお勧めします。Markdownリンター(文法標準化ツール)を使用すれば、後ですべてのコールアウトを自動的に大文字に一括変換できるため、作成時は楽な小文字で書き、必要に応じてツールで変換するのが効率的です。
例
> [!note]
> これはノートコールアウトです。
> [!warning]
> これは警告コールアウトです。
> [!tip] カスタムタイトル
> タイトルを追加することができます。
Markdownプラットフォーム別コールアウト/通知サポート比較
コールアウトタイプ | GitHub | GitLab | Obsidian |
---|---|---|---|
NOTE | ✅ | ✅ | ✅ |
TIP | ✅ | ✅ | ✅ |
IMPORTANT | ✅ | ✅ | ✅ |
WARNING | ✅ | ✅ | ✅ |
CAUTION | ✅ | ✅ | ✅ |
info | ❌ | ❌ | ✅ |
todo | ❌ | ❌ | ✅ |
abstract | ❌ | ❌ | ✅ |
summary | ❌ | ❌ | ✅ |
tldr | ❌ | ❌ | ✅ |
hint | ❌ | ❌ | ✅ |
success | ❌ | ❌ | ✅ |
check | ❌ | ❌ | ✅ |
done | ❌ | ❌ | ✅ |
question | ❌ | ❌ | ✅ |
help | ❌ | ❌ | ✅ |
faq | ❌ | ❌ | ✅ |
attention | ❌ | ❌ | ✅ |
failure | ❌ | ❌ | ✅ |
fail | ❌ | ❌ | ✅ |
missing | ❌ | ❌ | ✅ |
danger | ❌ | ❌ | ✅ |
error | ❌ | ❌ | ✅ |
bug | ❌ | ❌ | ✅ |
example | ❌ | ❌ | ✅ |
quote | ❌ | ❌ | ✅ |
cite | ❌ | ❌ | ✅ |
Obsidianが25種類の多様なコールアウトを提供していますが、実際には5種類の共通タイプのみを使用することを強く推奨します。
主な理由:
- 選択疲れの軽減:25個の中から悩む必要がなく、5個だけ覚えればよい
- 執筆への集中:コールアウト選択に時間を費やさず、内容に集中可能
- 一貫性の維持:チームやプロジェクト全体で統一されたスタイルを構築
- 互換性の保証:GitHub、GitLabなど、どのプラットフォームでも同様に動作
- 認知負荷の最小化:読者も馴染みのある5種類だけを理解すればよい
推奨5種類のタイプ:NOTE(情報)、TIP(ヒント)、IMPORTANT(重要)、WARNING(警告)、CAUTION(注意)
この5種類だけで99%の状況を効果的に表現できます。より多くの選択肢が常により良いわけではありません。
基本情報コールアウト
ユーザーが認知して進むべき基本的な情報やメモを表示する際に使用します。
Note
GitHub | GitLab | Obsidian |
---|---|---|
✅ | ✅ | ✅ |
基本的な情報やメモを表示します。
Info
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
情報的な内容や案内事項を表示します。
Todo
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
やることやタスクリストを表示します。
ヘルプ・提案コールアウト
ユーザーに役立つヒントや重要な情報を強調する際に使用します。
Tip
GitHub | GitLab | Obsidian |
---|---|---|
✅ | ✅ | ✅ |
有用なヒントや提案事項を表示します。
Hint
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
ヒントや示唆を提供する際に使用します。
Important
GitHub | GitLab | Obsidian |
---|---|---|
✅ | ✅ | ✅ |
重要な情報やコア内容を強調します。
質問・ヘルプコールアウト
ユーザーの疑問点を解決したり、ヘルプを提供する際に使用します。
Question
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
質問や疑問事項を表示します。
Help
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
ヘルプや使用方法の案内を提供します。
FAQ
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
よくある質問と回答を表示します。
警告・注意コールアウト
ユーザーに注意事項や警告を伝える際に使用します。
Warning
GitHub | GitLab | Obsidian |
---|---|---|
✅ | ✅ | ✅ |
注意が必要な事項を警告します。
Caution
GitHub | GitLab | Obsidian |
---|---|---|
✅ | ✅ | ✅ |
気をつけるべき内容や危険要素をお知らせします。
Attention
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
特に注目すべき内容を強調します。
成功・完了コールアウト
成功した結果や完了した作業を表示する際に使用します。
Success
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
成功した結果や肯定的な状態を表示します。
Check
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
確認済みの内容や検証された情報を表示します。
Done
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
完了した作業や仕上がった内容を表示します。
要約・整理コールアウト
内容を要約したり、要点のみを簡潔にまとめる際に使用します。
Abstract
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
文書や内容の概要を提供します。
Summary
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
主要な内容を要約して整理します。
TLDR
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
Too Long; Didn't Read - 長い内容の要点のみを簡潔にまとめます。
エラー・問題コールアウト
エラー、失敗、問題点などを表示する際に使用します。
Failure
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
失敗した結果や問題が発生した状況を表示します。
Fail
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
失敗状況や誤った結果を表します。
Missing
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
欠落した内容や不足している情報を表示します。
Danger
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
危険な状況や深刻な問題を警告します。
Error
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
エラー状況やエラーメッセージを表示します。
Bug
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
バグやソフトウェアの不具合を報告する際に使用します。
例・引用コールアウト
例を示したり、他の出典の内容を引用する際に使用します。
Example
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
具体的な例やサンプルコードを提供します。
Quote
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
他の出典からの引用文や名言を表示します。
Cite
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
参考資料や出典を明示する際に使用します。
高度な機能
タイトル追加(全プラットフォーム対応)
GitHub | GitLab | Obsidian |
---|---|---|
✅ | ✅ | ✅ |
コールアウトタイプの後にタイトルを追加することができます。
折りたたみ・展開機能(Obsidian専用)
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
文法:
> [!info]- デフォルトで折りたたまれた状態
> マイナス(-)記号を使用すると、デフォルトで折りたたまれた状態で表示されます。
> [!info]+ デフォルトで展開された状態
> プラス(+)記号を使用すると、デフォルトで展開された状態で表示されます。
レンダリング結果:
デフォルトで折りたたまれた状態
マイナス(-)記号を使用すると、デフォルトで折りたたまれた状態で表示されます。
デフォルトで展開された状態
プラス(+)記号を使用すると、デフォルトで展開された状態で表示されます。
ネストしたコールアウト(Obsidian専用)
GitHub | GitLab | Obsidian |
---|---|---|
❌ | ❌ | ✅ |
文法:
> [!warning] 外部コールアウト
> これは外部コールアウトです。
>
> > [!tip] 内部コールアウト
> > コールアウト内に他のコールアウトをネストすることができます。
レンダリング結果:
これは外部コールアウトです。
コールアウト内に他のコールアウトをネストすることができます。