Quick Syntax

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

---

출처를 인용하거나 보조 맥락을 분리할 때는 blockquote를, 큰 내용 전환에만 thematic break를 씁니다. 여러 줄 인용은 각 줄과 빈 줄에도 >를 붙여 portable하게 유지하고, 위험·필수 조치는 일반 인용문 대신 renderer가 지원하는 alert 또는 분명한 본문 문장으로 표현합니다.

문법

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

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

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

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

여러 줄 인용은 각 줄에 > 를 붙이면 원문 구조가 분명해진다

CommonMark는 문단이 이어지는 lazy continuation을 허용하므로 모든 줄에 >가 반드시 필요한 것은 아니다. 다만 인용 안의 새 문단과 빈 줄에도 >를 붙이면 원문만 읽어도 범위가 분명하고, formatter나 다른 renderer를 거칠 때도 의도를 확인하기 쉽다. 중첩 인용은 >>처럼 >를 반복해 표현한다.

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

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

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

## 참고

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

---

## 다음 단계

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

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

선택 기준

주의할 점