블로그 글을 마크다운으로 쓰다 보면 이런 일을 겪습니다. 분명히 별표 두 개로 감싸서 굵게를 만들었는데, 발행하고 보니 글에 별표가 그대로 ** 이렇게 노출돼 있어요. 굵게는 안 먹고요.
마크다운(Markdown): 글에 서식을 주는 간단한 문법.
**단어**처럼 별표 두 개로 감싸면 굵게가 됩니다.
더 당황스러운 건, 어떤 줄에서만 이런다는 겁니다. 같은 방식으로 썼는데 대부분은 멀쩡하고 특정 줄만 깨져요. 저도 이것 때문에 발행이 막힌 적이 있어서, 원인을 파고든 김에 정리합니다. 한국어로 글 쓰는 분이라면 언젠가 꼭 만나는 함정이거든요.
언제 깨지나: 괄호로 끝난 굵게 + 바로 붙은 조사
AI가 쓴 초안에서 깨진 문장은 이거였습니다.
로그인할 **열쇠(비밀번호·토큰)**가 필요합니다.
**열쇠(비밀번호·토큰)**를 굵게로 만들려던 건데, 발행하면 별표가 그대로 보였어요. 범인은 닫는 별표 바로 앞뒤에 있었습니다.
- 닫는
**바로 앞이)— 괄호, 즉 문장부호입니다. - 닫는
**바로 뒤가가— 한글 조사, 즉 공백도 문장부호도 아닌 글자입니다.
이 조합이면 마크다운은 그 **를 “닫는 표시로 인정하지 않습니다.” 안 닫히니 굵게가 성립 못 하고, 별표가 글자로 그냥 남는 거죠.
처음엔 범인을 잘못 짚었다
사실 이 줄을 처음 잡은 건 제 눈이 아니라, 발행을 맡은 에이전트(Cowork)의 발행 전 검사였어요. 그 줄에는 굵게가 두 개 있었습니다 — **열쇠(비밀번호·토큰)**와 **글 쓰는 쪽은 … 갖지 않고**. Cowork가 쓰고 제가 글 쓰는 쪽 AI(Claude Code)에 전달한 수정 요청서는 두 번째 굵게를 범인으로 지목했어요. «68행 두 번째 굵게의 닫는 ** 가 …갖지 않고**(파일만 만들고), 처럼 바로 뒤에 여는 괄호 ( 가 붙어 있다.»
AI는 요청서대로 고치기 전에, 어느 별표가 실제로 깨지는지부터 실험으로 확인했습니다. 결과는 반대였어요. 범인은 첫 번째 굵게, 바로 위에서 본 …토큰)**가 쪽이었습니다. 이 결과를 듣고 제가 보낸 답이 이거예요. «좋아. 내가 미처 보지 못한걸 잘 잡아서 엉뚱하게 코드수정을 할뻔했네. 고마워. 진행해.»
| 요청서의 진단 | 실험 뒤 결론 | |
|---|---|---|
| 누가 | Cowork(발행 쪽) | Claude Code(글 쓰는 쪽) |
| 지목한 굵게 | 두 번째 **글 쓰는 쪽은 … 갖지 않고** | 첫 번째 **열쇠(비밀번호·토큰)** |
| 닫는 별표 자리 | …갖지 않고**( — 뒤에 여는 괄호 | …토큰)**가 — 앞에 닫는 괄호, 뒤에 조사 |
| 근거 | 규칙(right-flanking)을 들어 설명 | 어느 별표가 깨지는지 실험 |
규칙을 인용한 진단도 빗나갈 수 있더라고요. 그래서 추론보다 실험이 먼저입니다. 아래에서 말할 “렌더해서 확인하라”와 같은 얘기예요.
왜 하필 이 조합인가
마크다운 표준(CommonMark)에는 별표가 여는 표시인지 닫는 표시인지 가리는 규칙이 있습니다. 정확한 이름은 어렵지만, 뜻은 단순해요. “닫는 별표는, 앞이 문장부호이면 뒤가 공백이나 문장부호일 때만 인정한다.”
CommonMark: 마크다운 문법의 표준 규격. 여러 프로그램이 이 규격을 따르므로, 여기서 안 되는 건 대부분의 곳에서 안 됩니다.
이 규칙을 우리 경우에 대보면 이렇습니다.
…토큰)**가→ 닫는 별표 앞은)(문장부호), 뒤는가(글자). 뒤가 공백도 부호도 아니라 → 인정 안 됨 → 안 닫힘.
그래서 별표가 그대로 노출됩니다. 규칙 자체가 애매한 상황(별표가 여는 건지 닫는 건지 헷갈리는 자리)을 피하려고 만들어진 건데, 하필 “괄호로 끝나고 조사가 붙는” 한국어 문장이 딱 그 함정에 빠지는 거예요.
왜 유독 한국어에서 자주 터지나
이 규칙 자체는 언어와 상관없습니다. 영어에서도 똑같이 적용돼요. 그런데 영어는 단어 뒤에 띄어쓰기를 하니 닫는 별표 뒤에 자연스럽게 공백이 옵니다(공백이면 인정됨). 반면 한국어는 조사(가·를·는·도…)가 단어에 딱 붙습니다. 띄어쓰기 없이요.
수학으로 치면, 같은 공식인데 대입하는 값이 달라서 결과가 갈리는 것과 같아요. 규칙(공식)은 하나인데, 한국어라는 값을 넣으면 유독 자주 걸립니다. 그래서 “한국어 특유의 함정”처럼 느껴지지만, 정확히는 한국어의 조사 문화가 이 규칙을 자주 건드리는 것입니다.
참고로, 용어 풀이 줄은 멀쩡합니다.
> **토큰(token)**: 프로그램이 쓰는 열쇠 문자열.
이건 닫는 별표 뒤가 :(문장부호)라서 규칙에 걸리지 않아요. 조사가 바로 붙는 본문 문장에서만 터집니다.
해결: 풀이를 굵게 밖으로 빼라
고치는 법은 간단합니다. 닫는 별표가 ) 바로 뒤에 오지 않게 하면 됩니다. 굵게 범위를 살짝 줄여, 괄호 풀이를 굵게 바깥으로 빼는 거예요.
❌ **열쇠(비밀번호·토큰)**가 필요합니다
✅ **열쇠**(비밀번호·토큰)가 필요합니다
의미는 그대로고, 오히려 강조도 더 정확해집니다 — 진짜 강조하고 싶은 건 “열쇠”지 괄호 속 풀이가 아니니까요.
눈으로 못 잡으니, 렌더해서 확인하라
이 버그의 무서운 점은 소스만 봐서는 멀쩡해 보인다는 겁니다. **열쇠(비밀번호·토큰)**가는 별표 짝이 맞아 보이잖아요. 그래서 AI에게 맡겨, 발행 전에 실제로 HTML로 렌더해서 “별표가 글자로 남았는지”를 자동으로 검사하는 관문을 하나 뒀습니다. 사람 눈으로 매번 잡는 건 결국 놓치거든요.
렌더(render): 마크다운을 실제 보이는 화면(HTML)으로 바꾸는 것. 깨짐은 바뀐 결과를 봐야 드러납니다.
관문을 둔 뒤에도 — 이 함정은 계속 나왔다
위의 관문은 AI가 만든 Lint-Draft.ps1이에요. 요청서가 짚은 건 이 한 줄만이 아니었습니다. «같은 계열 버그가 생성 단계에서 반복 유입되고 있다: 부호·공백에 인접한 **, 짝 안 맞는 백틱(코드가 본문 삼킴), 한 줄에 용어정의 2개(줄바꿈 누락).» 그래서 발행 쪽 검사에만 기대지 말고 글을 만드는 쪽에서 먼저 막기로 했고, AI가 깨진 샘플은 막고 멀쩡한 샘플은 통과시키는지 시험한 뒤 PR #43으로 합쳤어요.
그 뒤로도 이 함정은 끝나지 않았어요. 9월 4일에는 초안 한 편이 «A: 코드 밖 리터럴 ‘**’ 6개 → 굵게가 안 닫혔다(닫는 ** 가 부호에 붙었는지 확인).»라는 메시지로 멈췄고, 같은 날 다른 초안도 같은 검사에 4개가 걸렸습니다. 9월 5일·9일·11일·13일 초안도 같은 A 검사에 걸렸어요. 9월 10일엔 괄호가 아니라 따옴표였습니다. «A 게이트가 잡은 건 실제 결함입니다 — **"…"** 처럼 닫는 별표가 따옴표에 붙어 굵게가 안 닫혔습니다.» 걸릴 때마다 AI가 닫는 별표를 고치고 검사를 다시 돌렸어요.
초안이 아닌 곳에서도 나왔습니다. 사이트 About 페이지에 별표가 깨진 채 남아 있던 걸 9월 26일에 수리 스크립트로 고쳤고, AI가 로그인 없는 공개 페이지로 따로 세어 확인했어요. «About의 별표도 0이 됐고, 그 자리는 굵은 글씨로 제대로 보입니다.»
그래서 뭘 하면 되나
한국어로 마크다운을 쓰는데 굵게가 안 먹으면, 이 순서로 보세요.
| 증상 | 원인 | 해결 |
|---|---|---|
별표 **가 글자로 그대로 보임 | 🔴 닫는 별표가 안 닫힘 | 닫는 ** 앞뒤를 확인 |
닫는 ** 앞이 )·" 등 부호 + 뒤가 조사 | 🔴 CommonMark 규칙에 걸림 | 🟢 풀이·부호를 굵게 밖으로 |
용어 풀이 줄(**용어**:)은 멀쩡 | 뒤가 :(부호)라 정상 | 손댈 것 없음 |
| 매번 눈으로 놓친다 | 소스만 봐선 안 보임 | 🟢 발행 전 HTML 렌더 검사 |
한 문장 요약: 닫는 **가 ) 같은 부호 뒤에 오고 그 뒤에 한글 조사가 바로 붙으면 굵게가 안 닫힌다. 풀이를 굵게 밖으로 빼고, 발행 전엔 렌더해서 확인하라.
마크다운은 쉬워 보이지만, 이렇게 문장부호와 언어가 얽히면 예상 밖으로 새는 지점이 있습니다. 특히 한국어는 조사가 붙는 특성 때문에 남들보다 더 자주 만나요. 규칙을 통째로 외울 필요는 없습니다 — “괄호로 끝나는 굵게 뒤에 조사가 붙으면 위험하다” 이 한 줄만 기억해도 대부분 피합니다. 그리고 확신이 안 서면, 눈이 아니라 렌더된 결과를 믿으세요.