숏컷 코드

> 중요한 참고 문장
> 두 줄 이상도 가능합니다.

---

문법

blockquote는 출처 있는 인용과 맥락 분리에 목적을 맞춰야 한다

blockquote의 원래 의미는 다른 소스에서 가져온 텍스트를 구별하는 것이다. 그러나 실무 기술 문서에서는 참고 메모, 보충 설명, 중요 문장을 시각적으로 분리하는 용도로도 많이 쓰인다. 목적이 분명할수록 독자에게 효과적이다. "이것은 인용이다"와 "이것은 주의 메모다"를 blockquote로 뒤섞으면 문서 구조가 모호해진다. GitHub의 alert 블록(> [!NOTE])은 이 혼용 문제를 해결하기 위한 확장이다.

<!-- 출처 인용 -->
> "Simple is better than complex." — PEP 20

<!-- 맥락 분리용 메모 -->
> 이 설정은 로컬 환경에서만 사용합니다.

여러 줄 인용은 각 줄에 > 를 붙여야 렌더러 간 일관성이 보장된다

CommonMark 규격에서 blockquote는 각 줄 앞에 > 를 붙이는 것이 원칙이다. 일부 렌더러는 > 없는 빈 줄까지 같은 블록으로 이어 주지만, 이 동작은 구현에 따라 다르다. 줄마다 > 를 명시하면 GitHub, GitLab, pandoc, 로컬 뷰어 등 렌더러 차이와 무관하게 안전하다. 중첩 인용은 >> 처럼 > 를 반복해 표현한다.

> 첫 번째 줄
> 두 번째 줄
>
> 새 단락도 `>`를 유지합니다.
>
> > 중첩 인용은 이렇게 표현합니다.

구분선 세 가지는 동일하지만 문서 컨벤션을 통일하는 것이 좋다

---, ***, ___ 모두 CommonMark 기준 thematic break로 동등하게 처리된다. 단, ---는 YAML 프런트매터 구분자와 동일한 문자열이기 때문에 문서 맨 위에 단독으로 쓰면 프런트매터 끝으로 오해될 수 있다. 대부분의 실무 저장소는 ---를 표준으로 채택하되, 문서 상단 근처에서는 위치를 주의해야 한다. 프로젝트 전체에서 한 가지 스타일만 쓰면 grep이나 diff에서 찾기 쉬워진다.

## 참고

> 이 설정은 로컬 환경에서만 사용합니다.

---

## 다음 단계

구분선을 남발하면 섹션 제목과 역할이 겹쳐 문서 계층이 흐려진다

제목(##, ###)이 이미 섹션을 나누고 있다면 그 사이에 구분선을 추가하는 것은 중복이다. 구분선이 효과적인 상황은 같은 제목 수준 안에서 완전히 다른 내용 덩어리가 시작될 때, 또는 제목 없이 긴 본문이 주제 전환을 해야 할 때이다. 짧은 문서에서 구분선이 3개 이상 나타나면 제목 계층 재설계를 먼저 고려하는 편이 낫다.

선택 기준

주의할 점