GitHub 마크다운 미리보기가 들쑥날쑥한 이유, 뭘까?

지금 일어나고 있는 일

원문을 확인해본 결과, 사용자가 겪는 현상은 꽤 흥미롭습니다. 같은 마크다운 파일이 어떨 땐 깔끔하게 렌더링되어 보이다가, 어떨 땐 갑자기 raw code(원본 코드) 상태로 표시된다는 것이죠. 더 놀라운 건 이 현상이 ‘무작위(random preview failure)’라는 점입니다.

commit(커밋)을 한 직후에 문제가 시작되었다고 했는데, 며칠 지나면 자동으로 정상화되기도 하고, 그대로 계속 깨진 채로 있기도 합니다. 심지어 다른 저장소(repository)에 정확히 같은 내용의 파일을 복사해도 여전히 미리보기가 실패한다고 했으니, 이건 단순한 파일 포맷 문제는 아닌 것 같습니다.

기술 스택 관점에서 보면

GitHub의 마크다운 렌더링 파이프라인(rendering pipeline)을 생각해보면, 여러 계층이 있습니다. 파일을 받아들이는 단계, 마크다운 파서(parser)를 거치는 단계, HTML로 변환하는 단계, 브라우저에서 표시하는 단계. 이 중 어느 한 지점에서 불안정성이 생기면 사용자 입장에서는 “왜 이게 되다 안 되다 하지?”라는 경험을 하게 됩니다.

원문에서 중요한 단서는 파일명입니다. README.jp.md라고 표시되어 있는데, 이건 일본어 메타데이터를 포함할 가능성이 있습니다. 혹은 문자 인코딩(encoding) 문제일 수도 있고요. 35년간 다양한 기술 스택을 보며 느낀 건, 문자 처리 계층은 언제나 예상 밖의 문제를 낳는다는 것입니다. UTF-8 인코딩, BOM(Byte Order Mark), 줄바꿈 형식(line ending) 같은 것들이 눈에 띄지 않게 동작하다가도, 특정 버전의 파서나 서버에 올라가면 갑자기 충돌을 일으킵니다.

이 현상이 말해주는 것들

시간이 지나면 자동으로 복구된다는 부분이 흥미롭습니다. 이건 보통 서버 측 캐시(cache) 갱신, 또는 비동기 작업 큐(asynchronous job queue)의 재처리(retry) 같은 메커니즘을 시사합니다. n8n이나 GitHub Actions 같은 자동화 도구로 인프라를 구축해본 입장에서 보면, GitHub도 분명히 백그라운드에서 여러 작업들을 관리하고 있을 겁니다. 파일이 올라오면 즉시 렌더링하는 게 아니라, 큐에 넣었다가 처리하는 방식이죠.

문제는 이 큐나 캐시 계층에서 특정 조건(특정 문자셋, 특정 파일 크기, 특정 마크다운 문법)에 따라 실패율이 달라진다는 겁니다. 그리고 “어제는 안 됐는데 오늘 되네?” 같은 경험은 보통 GitHub 측 서버 재배포(deployment)나 알고리즘 업데이트가 있었을 때 일어납니다.

왜 1인 운영자와 소규모 팀에게 중요한가

GitHub은 이제 단순한 코드 저장소가 아니라, 문서화(documentation), 자동화 워크플로우(workflow), 협업 플랫폼으로 작동하고 있습니다. README 파일이 제대로 보이지 않는다는 건 프로젝트의 첫인상이 망가진다는 뜻이고, 특히 국제화(localization)를 지원하려는 창작자(이 경우 일본어 README)에겐 신뢰 문제로 번질 수 있습니다.

더군다나 이 버그가 “무작위”라면? 자동화 테스트(automated testing)나 CI/CD 파이프라인에서도 잡아내기 어렵습니다. 내가 작성한 마크다운이 정말 맞는지 확인하려고 해도, GitHub 자체의 렌더러가 일관성 있는 피드백을 주지 않으니까요.

남아 있는 의문들

여기서 계속 지켜봐야 할 지점이 있습니다: GitHub은 이 렌더링 불안정성을 공식적으로 인정하고 있는가? 그리고 실제로 파일 메타데이터(특히 non-ASCII 문자열)와 연관이 있는가 하는 부분입니다.

이 이슈는 다음 편에서 GitHub 공식 문서나 커뮤니티 응답이 어떻게 흘러갔는지 이어서 다뤄보겠습니다.