마크다운 콜아웃 가이드

콜아웃이란?

기본 마크다운에서는 단순한 인용문(>)만 제공하지만, GitHub이 향상된 디자인을 도입하면서 글쓴이가 독자에게 특정 내용을 강조하고 의도를 명확히 전달할 수 있는 콜아웃 기능을 제공하기 시작했습니다. 이 기능은 GitLab과 Obsidian 등 다른 마크다운 렌더링 도구들에서도 채택되어 널리 사용되고 있습니다.

기본 마크다운 인용문과의 차이

기본 인용문 문법:

> 이것은 기본 마크다운 인용문입니다.
> 단순한 회색 세로선과 들여쓰기만 제공됩니다.

렌더링 결과:

이것은 기본 마크다운 인용문입니다. 단순한 회색 세로선과 들여쓰기만 제공됩니다.

반면 콜아웃은 색상, 아이콘, 제목 등 풍부한 시각적 요소를 제공하여 내용의 성격을 명확히 전달할 수 있습니다.

기본 사용법

콜아웃은 다음과 같은 문법으로 사용합니다:

> [!타입]
> 콜아웃 내용

[!tip] 대소문자 규칙 콜아웃 타입은 대소문자를 구분하지 않습니다. [!NOTE], [!note], [!Note] 모두 동일하게 작동합니다.

하지만 일관성을 위해 하나의 규칙을 정해서 사용하는 것이 좋습니다:

소문자 ([!note]): 타이핑이 편하고 빠름 (Shift 키 불필요)
대문자 ([!NOTE]): 시각적으로 눈에 잘 띄고 공식적인 느낌

권장사항: 소문자 사용을 추천합니다. 마크다운 린터(문법 표준화 도구)를 사용하면 나중에 모든 콜아웃을 자동으로 대문자로 일괄 변환할 수 있기 때문에, 작성할 때는 편한 소문자로 쓰고 필요시 도구로 변환하는 것이 효율적입니다.

예시

> [!note]
> 이것은 노트 콜아웃입니다.

> [!warning]
> 이것은 경고 콜아웃입니다.

> [!tip] 커스텀 제목
> 제목을 추가할 수 있습니다.

마크다운 플랫폼별 콜아웃/알림 지원 비교

콜아웃 타입	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	❌	❌	✅

권장사항 - 간결함이 생산성이다

옵시디언이 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
❌	❌	✅

오류 및 문제 콜아웃

오류, 실패, 문제점 등을 표시할 때 사용합니다.

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] 내부 콜아웃
> > 콜아웃 안에 다른 콜아웃을 중첩할 수 있습니다.

렌더링 결과: