숏컷 코드

> [!NOTE]
> 이 문단은 참고 메모입니다.

> [!WARNING]
> 주의가 필요한 설정입니다.

> [!TIP]
> 명령 실행 전에 `.env.example`을 먼저 복사해 두면 설정 실수를 줄일 수 있습니다.

문법

GitHub 전용 확장이라 렌더러 이식성을 먼저 확인해야 한다

alert 블록은 > [!NOTE] 처럼 blockquote 앞에 키워드를 붙이는 GitHub 고유 확장 문법이다. GitHub.com과 GitHub Enterprise에서는 색상·아이콘이 붙은 강조 박스로 렌더링되지만, CommonMark 호환 렌더러(예: pandoc 기본 모드, MkDocs 기본 테마)에서는 단순 blockquote로 폴백되거나 키워드가 그대로 노출된다. MDX 기반 사이트처럼 자체 컴포넌트 시스템을 쓰는 환경에서는 이 문법 대신 전용 <Callout> 같은 JSX 컴포넌트가 더 안전한 선택이다.

> [!IMPORTANT]
> 이 설정을 잘못 입력하면 배포가 실패합니다.

심각도 5단계 중 목적에 맞는 키워드를 골라야 한다

GitHub는 NOTE, TIP, IMPORTANT, WARNING, CAUTION 다섯 단계를 제공한다. NOTE는 읽으면 도움이 되는 보조 정보, TIP은 생산성을 높이는 선택적 조언, IMPORTANT는 놓치면 기능이 깨지는 필수 정보, WARNING은 잠재적 손실·위험 경고, CAUTION은 되돌리기 어려운 심각한 부작용에 적합하다. WARNING과 CAUTION을 구분하지 않고 남발하면 독자가 실제 위험 수준을 파악하기 어려워진다.

> [!CAUTION]
> 이 명령은 데이터베이스를 초기화합니다. 되돌릴 수 없습니다.

알림 블록이 너무 많으면 강조 효과가 사라진다

한 문서에 alert 블록이 5개 이상 등장하면 독자는 모든 칸을 동등하게 중요하다고 느끼거나 아예 읽지 않게 된다. 실무 기술 문서에서는 페이지당 1–3개를 기준으로 삼고, 일반 본문으로 충분히 전달할 수 있는 내용은 alert로 감싸지 않는 편이 더 효과적이다.

<!-- 나쁜 예: 본문 전체가 알림 블록 -->
> [!NOTE]
> 설치합니다.
> [!TIP]
> 경로를 확인합니다.
> [!WARNING]
> 재시작이 필요합니다.

<!-- 좋은 예: 정말 중요한 경고 하나만 -->
npm install 후 서버를 재시작합니다.

> [!WARNING]
> `.env` 파일이 없으면 서버 시작 시 즉시 오류가 발생합니다.

기존 blockquote와 공존하므로 의도를 명확히 표기해야 한다

> 기호만 쓰는 일반 blockquote와 > [!NOTE] 형태의 alert는 같은 > 문자로 시작하기 때문에 혼용하면 의도가 불분명해질 수 있다. 인용 출처를 나타내는 곳에는 일반 blockquote를, 독자 행동을 유도하는 강조에는 alert 키워드를 일관되게 사용하면 문서 구조가 더 명확하다.

선택 기준

주의할 점