✈️ Go Up

이요의 홀

Go to Nav

마크다운 콜아웃 가이드

콜아웃이란?

기본 마크다운에서는 단순한 인용문(>)만 제공하지만, 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가지 공통 타입만 사용하는 것을 강력히 권장합니다.

핵심 이유:

  1. 선택 피로 감소: 25개 중 고민할 필요 없이 5개만 기억하면 됨
  2. 글쓰기 집중: 콜아웃 선택에 시간을 쓰지 않고 내용에 집중 가능
  3. 일관성 유지: 팀이나 프로젝트 전반에서 통일된 스타일 구축
  4. 호환성 보장: GitHub, GitLab 등 어느 플랫폼에서든 동일하게 작동
  5. 인지 부하 최소화: 독자도 익숙한 5가지만 이해하면 됨

권장 5가지 타입: NOTE(정보), TIP(팁), IMPORTANT(중요), WARNING(경고), CAUTION(주의)

이 5가지만으로도 99%의 상황을 효과적으로 표현할 수 있습니다. 더 많은 선택지가 항상 더 좋은 것은 아닙니다.


기본 정보 콜아웃

사용자가 인지하고 넘어가야 할 기본적인 정보나 메모를 표시할 때 사용합니다.

Note

GitHub GitLab Obsidian
Note

기본적인 정보나 메모를 표시합니다.

Info

GitHub GitLab Obsidian
Info

정보성 내용이나 안내사항을 표시합니다.

Todo

GitHub GitLab Obsidian
Todo

할일이나 작업 목록을 표시합니다.

도움말 및 제안 콜아웃

사용자에게 도움이 되는 팁이나 중요한 정보를 강조할 때 사용합니다.

Tip

GitHub GitLab Obsidian
Tip

유용한 팁이나 제안사항을 표시합니다.

Hint

GitHub GitLab Obsidian
Hint

힌트나 암시를 제공할 때 사용합니다.

Important

GitHub GitLab Obsidian
Important

중요한 정보나 핵심 내용을 강조합니다.

질문 및 도움 콜아웃

사용자의 의문점을 해결하거나 도움을 제공할 때 사용합니다.

Question

GitHub GitLab Obsidian
Question

질문이나 의문사항을 표시합니다.

Help

GitHub GitLab Obsidian
Help

도움말이나 사용법 안내를 제공합니다.

FAQ

GitHub GitLab Obsidian
Faq

자주 묻는 질문과 답변을 표시합니다.

경고 및 주의 콜아웃

사용자에게 주의사항이나 경고를 전달할 때 사용합니다.

Warning

GitHub GitLab Obsidian
Warning

주의가 필요한 사항을 경고합니다.

Caution

GitHub GitLab Obsidian
Caution

조심해야 할 내용이나 위험 요소를 알립니다.

Attention

GitHub GitLab Obsidian
Attention

특별히 주목해야 할 내용을 강조합니다.

성공 및 완료 콜아웃

성공적인 결과나 완료된 작업을 표시할 때 사용합니다.

Success

GitHub GitLab Obsidian
Success

성공적인 결과나 긍정적인 상태를 표시합니다.

Check

GitHub GitLab Obsidian
Check

확인된 내용이나 검증된 정보를 표시합니다.

Done

GitHub GitLab Obsidian
Done

완료된 작업이나 마무리된 내용을 표시합니다.

요약 및 정리 콜아웃

내용을 요약하거나 핵심만 간단히 정리할 때 사용합니다.

Abstract

GitHub GitLab Obsidian
Abstract

문서나 내용의 개요를 제공합니다.

Summary

GitHub GitLab Obsidian
Summary

주요 내용을 요약해서 정리합니다.

TLDR

GitHub GitLab Obsidian
Tldr

Too Long; Didn't Read - 긴 내용의 핵심만 간단히 정리합니다.

오류 및 문제 콜아웃

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

Failure

GitHub GitLab Obsidian
Failure

실패한 결과나 문제가 발생한 상황을 표시합니다.

Fail

GitHub GitLab Obsidian
Fail

실패 상황이나 잘못된 결과를 나타냅니다.

Missing

GitHub GitLab Obsidian
Missing

누락된 내용이나 빠진 정보를 표시합니다.

Danger

GitHub GitLab Obsidian
Danger

위험한 상황이나 심각한 문제를 경고합니다.

Error

GitHub GitLab Obsidian
Error

오류 상황이나 에러 메시지를 표시합니다.

Bug

GitHub GitLab Obsidian
Bug

버그나 소프트웨어 결함을 보고할 때 사용합니다.

예제 및 인용 콜아웃

예시를 보여주거나 다른 출처의 내용을 인용할 때 사용합니다.

Example

GitHub GitLab Obsidian
Example

구체적인 예제나 샘플 코드를 제공합니다.

Quote

GitHub GitLab Obsidian
Quote

다른 출처의 인용문이나 명언을 표시합니다.

Cite

GitHub GitLab Obsidian
Cite

참고자료나 출처를 명시할 때 사용합니다.

고급 기능

제목 추가 (모든 플랫폼 지원)

GitHub GitLab Obsidian
커스텀 제목

콜아웃 타입 뒤에 제목을 추가할 수 있습니다.

접기/펼치기 기능 (Obsidian 전용)

GitHub GitLab Obsidian

문법:

> [!info]- 기본적으로 접힌 상태
> 마이너스(-) 기호를 사용하면 기본적으로 접힌 상태로 표시됩니다.

> [!info]+ 기본적으로 펼쳐진 상태
> 플러스(+) 기호를 사용하면 기본적으로 펼쳐진 상태로 표시됩니다.

렌더링 결과:

기본적으로 접힌 상태

마이너스(-) 기호를 사용하면 기본적으로 접힌 상태로 표시됩니다.

기본적으로 펼쳐진 상태

플러스(+) 기호를 사용하면 기본적으로 펼쳐진 상태로 표시됩니다.

중첩 콜아웃 (Obsidian 전용)

GitHub GitLab Obsidian

문법:

> [!warning] 외부 콜아웃
> 이것은 외부 콜아웃입니다.
> 
> > [!tip] 내부 콜아웃
> > 콜아웃 안에 다른 콜아웃을 중첩할 수 있습니다.

렌더링 결과:

외부 콜아웃

이것은 외부 콜아웃입니다.

내부 콜아웃

콜아웃 안에 다른 콜아웃을 중첩할 수 있습니다.