AX 팁 19 — 한글 섞인 마크다운 표 칸 맞추기

작성

  • AX 팁
  • Claude Code
  • 개발 환경 자동화
  • 마크다운

한글이 섞인 마크다운 표를 원문(터미널·git diff)에서도 반듯하게 보려면, 글자 수가 아니라 화면에 차지하는 칸 수로 너비를 재야 합니다. 유니코드의 East Asian Width 속성에서 W(넓음)·F(전각)인 글자를 2칸, 나머지를 1칸으로 세고 칸마다 가장 넓은 값에 맞춰 공백을 채우면 됩니다. 저는 이 계산을 117줄짜리 파이썬 스크립트로 만들어 두고, 마크다운을 고친 커밋마다 그 파일에만 돌립니다.

인쇄한 표의 칸을 맞추는 여성 모습 사진 AI 생성 이미지

지난 편에서는 깨진 링크를 잡는 검사를 다뤘습니다. 이번 편은 그보다 훨씬 작은 문제, 표의 세로줄 하나 이야기입니다.

왜 원문에서 표의 세로줄이 자꾸 어긋났을까?

에이전트에게 주는 규칙 문서를 한 저장소에 모아 두고 씁니다. 규칙이 늘면서 표도 늘었고, 2026년 11월 13일에 세어 보니 git 이 추적하는 마크다운 729개 중 표가 있는 파일이 198개였습니다.

이 표들은 대부분 에이전트가 씁니다. 에이전트는 표를 쓸 때 칸을 맞추려고 공백을 넣긴 하는데, 한글 칸이 나오면 세로줄 | 이 오른쪽으로 밀립니다. 렌더링된 화면에서는 아무 문제가 없지만, 저는 이 문서를 대부분 터미널과 diff 로 읽습니다. 줄마다 | 위치가 다르면 어느 값이 어느 칸인지 눈으로 따라가기가 꽤 피곤합니다. 결국 2026년 10월 18일에 「문서 표 줄맞춤도 항상 맞춰 달라」고 규칙에 적었고, 같은 날 스크립트를 만들었습니다.

소스에서 꼭 맞춰야 할까?

검색해 보면 「마크다운 표 한글 정렬 깨짐」을 묻는 글이 꽤 있고, 답은 대개 두 갈래입니다. 하나는 렌더러가 칸 너비를 알아서 정하니 원문 정렬은 몰라도 된다는 쪽이고(마크다운 표 작성법 정리), 다른 하나는 렌더링 화면 자체가 깨지는 경우 글꼴 문제라는 쪽입니다(Obsidian 포럼의 한글 등폭 글꼴 질문).

둘 다 맞는 말입니다. 다만 제 경우는 문서를 사람이 렌더링 화면으로 읽는 일보다 원문으로 읽는 일이 훨씬 많았습니다. 리뷰도 diff 로 하고, 에이전트가 고친 결과도 터미널에서 확인합니다. 원문이 주로 읽히는 문서라면 원문 정렬이 곧 가독성입니다.

글자 수로 세면 왜 틀릴까?

대부분의 단순한 정렬 방식은 문자열 길이, 즉 글자 하나를 1칸으로 셉니다. 영문과 숫자는 그게 맞습니다. 그런데 한글 음절은 등폭 글꼴에서 영문 두 글자만큼 자리를 차지합니다. 스크립트의 폭 함수로 직접 재 보면 가나다 는 글자 수 3, 표시 폭 6 이고 abc 는 둘 다 3 입니다. 글자 수로 맞추면 한글이 든 줄만 그만큼 밀립니다.

이 폭 구분은 유니코드 표준 부속서 11번(East Asian Width)에 정의돼 있고, 파이썬은 표준 라이브러리 unicodedata 로 바로 읽을 수 있습니다. 추가 패키지가 필요 없다는 점이 이 방식을 고른 이유였습니다.

표 칸 너비를 세는 방법글자 수로 셈: 가나다 = 3칸, 한글이 든 줄만 세로줄이 밀림, diff 에서 칸을 눈으로 따라가기 어려움 → 표시 폭으로 셈: 가나다 = 6칸, 모든 줄의 세로줄이 같은 위치, 커밋 전 한 번 돌려 맞춤글자 수로 셈가나다 = 3칸한글이 든 줄만세로줄이 밀림diff 에서 칸을눈으로 따라가기어려움표시 폭으로 셈가나다 = 6칸모든 줄의 세로줄이같은 위치커밋 전 한 번 돌려맞춤
표 칸 너비를 세는 방법

바꾼 방법: 폭을 재고, 모르는 표는 건드리지 않는다

핵심은 폭 함수 한 줄입니다.

import unicodedata

def width(s):
    """터미널 표시 폭 — 전각(W·F)은 2칸"""
    return sum(2 if unicodedata.east_asian_width(c) in ("W", "F") else 1 for c in s)

나머지는 이 폭으로 칸마다 최댓값을 구해 공백을 채우는 일입니다. 다만 실제 문서에 돌려 보면 예외가 몇 가지 나와서, 그것을 하나씩 막는 데 줄이 더 들었습니다.

  • 칸을 나눌 때 백틱으로 감싼 코드 안의 | 와 역슬래시로 이스케이프한 \| 는 나누지 않습니다. 명령 예시가 든 칸이 둘로 쪼개지는 것을 막습니다.
  • 줄마다 칸 수가 다르거나 닫는 | 가 없는 표는 손대지 않고 그대로 둡니다. 빈 칸을 채워 넣으면 정렬이 아니라 내용 변경이 되기 때문입니다.
  • 코드 펜스 안의 줄은 표처럼 생겨도 건너뜁니다.
  • 구분 행의 :---: 같은 정렬 표시는 콜론 위치를 지키면서 길이만 늘립니다.

쓰는 법은 두 가지입니다. 파일을 주면 정렬해 덮어쓰고, --check 를 붙이면 아무것도 바꾸지 않고 어긋난 파일 이름만 찍은 뒤 하나라도 있으면 종료 코드 1 을 냅니다.

python3 scripts/work/md-table-align.py --check docs/INDEX.md
python3 scripts/work/md-table-align.py docs/INDEX.md

저장소 전체를 한 번에 맞추면 안 되는 이유는?

처음 만든 날 색인 문서 하나를 정렬했더니 그 커밋에서만 391줄이 바뀌었습니다(2026년 10월 18일 커밋 통계). 표 하나의 공백만 바뀐 것인데도 diff 는 그 문서를 통째로 다시 쓴 것처럼 보입니다. 이런 커밋이 다른 변경과 섞이면 리뷰가 어려워집니다.

그래서 규칙을 「내가 이번에 고친 파일에만 돌린다」로 정했습니다. 커밋 절차의 한 단계로 넣어 두었고, 남의 파일을 전체 정렬하는 것은 금지했습니다. 또 문서 하나는 다른 검사 스크립트의 정규식이 공백 없는 표를 전제하고 있어서 당분간 정렬 대상에서 뺐습니다. 처음 정렬했을 때 그 검사가 실패 2건을 내서 알게 된 일입니다. 보기 좋은 원문보다 다른 도구가 그 원문을 읽을 수 있는 쪽을 먼저 지켰습니다.

커밋 전 표 정렬 흐름마크다운 수정 → 바꾼 .md 만 고름; 바꾼 .md 만 고름 → 정렬 제외 문서?; 정렬 제외 문서? → 표시 폭으로 정렬 (아니오); 정렬 제외 문서? → 커밋 (예); 표시 폭으로 정렬 → 커밋아니오예마크다운 수정바꾼 .md 만 고름정렬 제외 문서?표시 폭으로 정렬커밋
커밋 전 표 정렬 흐름 — 바꾼 마크다운에만 돌린다

2026년 10월 23일에는 인자 처리를 argparse 로 바꿨습니다. -h 를 주면 설명만 보여 주고, 모르는 옵션은 종료 코드 2 로 거부합니다. 이 스크립트는 기본 동작이 파일 덮어쓰기라서, 도움말을 보려다 실제로 파일이 바뀌는 일을 막아야 했습니다.

지금은 무엇이 달라졌을까?

2026년 11월 13일에 추적 중인 마크다운 729개 전체에 --check 를 돌렸더니 어긋난 파일이 0개였습니다. 고친 파일마다 정렬하는 습관이 한 달 가까이 쌓이니, 표가 있는 198개 파일이 모두 맞춰진 상태가 됐습니다.

체감으로 가장 큰 변화는 diff 를 읽는 속도입니다. 에이전트가 표에 행 하나를 더하면 그 행만 diff 에 나오고, 세로줄이 맞아 있으니 새 값이 어느 칸인지 바로 보입니다. 다음 편에서는 같은 한글 문제의 다른 얼굴, 한글 파일명이 기기마다 다르게 저장되는 문제를 다룰 생각입니다.

자주 묻는 질문

렌더링된 화면에서도 표가 깨지면 이 방법으로 고쳐지나요?

아닙니다. 렌더링된 HTML 표는 원문 공백과 무관하게 칸 너비를 정합니다. 화면에서 깨진다면 글꼴이나 편집기 설정 문제일 가능성이 높고, 이 스크립트는 원문을 읽을 때만 도움이 됩니다.

그리스 문자나 기호처럼 폭이 애매한 글자는 어떻게 세나요?

East Asian Width 에는 환경에 따라 1칸도 2칸도 되는 A(애매함) 분류가 있습니다. 제 스크립트는 W·F 만 2칸으로 세므로 A 는 1칸으로 칩니다. 제 문서에는 그런 글자가 드물어 이 기본값으로 충분했지만, 동아시아 글꼴 환경을 주로 쓴다면 A 를 2칸으로 세는 선택지를 두는 편이 낫습니다.

이모지가 든 표도 맞춰지나요?

대부분의 그림 이모지는 W 로 분류돼 2칸으로 세집니다. 다만 여러 코드 포인트를 이어 붙인 이모지는 글자 단위로 세는 이 방식에서 어긋날 수 있습니다. 저는 문서에 이모지를 거의 쓰지 않아 따로 처리하지 않았습니다.

사이트를 만들어볼까요?

무료 상담 받기