코드 안의 백틱 때문에 Markdown 코드 블록이 끊길 때

SmartInfoBank 운영자 · 작성 2026-10-21 · 수정 2026-10-21 · 6분

Markdown 문서에서 기술 문서나 셸 스크립트, 마크다운 자체 문법을 설명하다 보면 코드 블록 안에 세 개의 백틱(```) 기호가 그대로 들어가야 하는 경우가 있습니다. 이때 일반적인 방법대로 양 끝을 백틱 세 개로만 묶으면 파서가 내부의 백틱을 닫는 울타리로 인식하여 블록이 중간에 끊기고, 나머지 코드가 일반 텍스트나 깨진 서식으로 밖으로 쏟아져 나오는 문제가 발생합니다.

단순한 텍스트 기호 변환이나 HTML 이스케이프를 무작정 적용하기 전에, Markdown 표준 명세가 정의하는 코드 울타리(Fenced Code Block)의 길이 규칙을 활용하면 원본 코드를 손상시키지 않고 안전하게 표현할 수 있습니다.

코드 울타리가 의도보다 일찍 닫히는 원인

GitHub Flavored Markdown(GFM) 명세에 따르면, 코드 울타리는 연속된 3개 이상의 백틱(`) 또는 물결표(~)로 시작합니다. 그리고 이 울타리는 시작 울타리와 동일한 문자 종류이면서 최소한 시작 울타리 이상의 개수를 가진 닫는 울타리를 만날 때까지 내부의 모든 줄을 문자 그대로(literal text) 담아냅니다.

만약 본문 코드에 이미 백틱 3개(```)가 포함되어 있는데 감싸는 외부 울타리 역시 백틱 3개로 설정하면, 파서는 코드 내부의 첫 백틱 3개를 유효한 닫는 울타리로 판단하고 코드 블록을 즉시 끝냅니다. 그 뒤에 이어지는 실제 코드와 마지막 닫는 울타리는 일반 문단이나 잘못된 구문으로 해석되어 문서 레이아웃 전체가 무너지게 됩니다.

바깥 울타리 백틱 길이를 늘리는 해결 원리

이 문제를 해결하는 표준 규격은 GFM 코드 울타리 명세에 명시되어 있습니다. 닫는 울타리는 반드시 시작 울타리의 문자 수와 '같거나 더 많은 수'여야 유효합니다. 따라서 내부 코드에 백틱이 3개 있다면, 블록을 감싸는 외부 여는 울타리와 닫는 울타리를 백틱 4개(````)로 늘려주면 됩니다.

내부 코드에 백틱 3개가 들어 있을 때 바깥을 4개로 감싸는 표준 동작 원리는 아래 검증된 예제와 같습니다.

본문에 ```를 그대로 보여 주려면 바깥을 ```` (네 개)로 감싸는 예제를 만든다. 여는 울타리와 닫는 울타리의 종류와 길이 규칙을 원문 명세와 대조한다.

안전한 울타리 작성과 확인 순서

본문에 백틱이 포함된 기술 예제를 안전하게 작성할 때는 다음 순서대로 단계를 밟습니다.

1. 내부 텍스트 백틱 개수 파악: 코드 블록 내부에 포함될 연속 백틱의 최대 개수를 확인합니다. 예를 들어 다른 코드 블록 문법을 예시로 들 경우 연속 백틱 3개가 포함됩니다.
2. 바깥 울타리 길이 결정: 내부 최대 연속 개수보다 최소 1개 이상 더 많은 백틱을 바깥 울타리로 정합니다. 내부가 3개라면 바깥은 4개(````) 이상으로 지정합니다.
3. 언어 식별자(info string) 부착: 필요한 경우 여는 울타리 바로 뒤에 공백 없이 언어 이름을 적습니다(예: ````markdown). 백틱 울타리의 정보 문자열 내부에는 백틱 문자가 포함되어서는 안 됩니다.
4. 닫는 울타리 일치: 블록을 닫을 때 여는 울타리와 동일한 문자(백틱)를 사용하고, 개수를 여는 울타리 이상으로 맞춥니다.
5. 렌더링 결과 확인: 내부의 백틱 3개와 코드 내용이 코드 서식 안에서 그대로 유지되고 외부로 빠져나오지 않는지 확인합니다.

자주 발생하는 실패 사례와 구문 충돌

울타리 길이를 늘려도 의도치 않은 서식 오류가 발생하는 대표적인 예외 상황들이 있습니다.

• 문자 혼용: 여는 울타리는 물결표(~~~~)로 시작하고 닫는 울타리는 백틱(````)으로 작성하면 닫는 울타리로 인정되지 않아 문서 끝까지 블록으로 처리됩니다. 물결표와 백틱은 섞어 쓸 수 없습니다.
• 들여쓰기 4칸 초과: 여는 울타리 앞에 공백을 4칸 이상 넣으면 GFM 명세상 울타리 코드 블록이 아닌 들여쓰기 코드 블록으로 파싱되어 울타리 자체가 텍스트로 노출됩니다. 울타리 앞 들여쓰기는 0~3칸 이내여야 합니다.
• 닫는 울타리의 공백 삽입: `` ``처럼 백틱 기호 사이에 공백이 들어가면 단일 울타리로 인정되지 않습니다. 울타리 기호는 반드시 연속되어야 합니다.
• 닫는 울타리 뒤 정보 문자열: 여는 울타리와 달리 닫는 울타리 뒤에는 공백만 올 수 있으며, 언어 이름이나 다른 문자가 붙으면 닫는 울타리로 인식되지 않습니다.

이 방법의 한계와 환경별 주의점

바깥 울타리 길이를 늘리는 방식은 CommonMark 및 GitHub Flavored Markdown 규격을 준수하는 표준 파서에서 완벽히 작동합니다. 그러나 오래된 간이 Markdown 라이브러리나 정규표현식 기반의 비표준 파서 중에는 오직 백틱 3개(```)만 고정적으로 인식하도록 하드코딩된 경우가 있습니다.

또한 이 규칙은 코드 블록 내부의 서식 종료 지점을 정확히 지정해 줄 뿐이며, 렌더링 엔진 내부의 문법 강조(syntax highlighting) 플러그인이 중첩된 언어 토큰을 어떻게 채색할지까지 보장하지는 않습니다. 복잡한 마크다운 문서를 배포하기 전에는 사용하는 정적 사이트 생성기나 렌더러가 CommonMark 표준의 가변 울타리 길이를 정상적으로 지원하는지 미리 확인해야 합니다.