README 외부 이미지 과다로 생기는 렌더링 누락 해결

외부 이미지 폭탄으로 README가 안 보임

오늘 머지한 PR 확인하려고 메인 레포 페이지 들어갔더니 README 중간이 통째로 비어있었음. 처음엔 마크다운 문법이 깨진 줄 알고 raw 파일을 열어봤는데 멀쩡함. 그런데 렌더된 페이지에서만 이미지 절반이 X 박스로 뜨고, 어떤 건 아예 placeholder조차 안 나옴.

원인 추적

확인해보니 외부 이미지 호스팅(블로그, 이슈 트래커, 외부 CDN) 링크를 별 생각 없이 박아둔 게 문제였음. 카운트해보니 단일 README에서 외부 도메인 이미지가 38개. GitHub은 외부 이미지를 자기 프록시로 한 번 캐싱해서 보여주는데, 한 페이지에 일정 개수를 넘기면 렌더링 자체가 타임아웃 나거나 일부가 누락됨. 조용히 실패해서 알아채기도 어려움.

정리한 방식

• 핵심 다이어그램은 레포 내부로 옮김. docs/images/ 폴더 만들고 png를 직접 커밋.
• 실시간 변하는 배지(빌드 상태, 커버리지)만 외부 유지. 어차피 동적이라 내부화 의미 없음.
• 외부 블로그 스크린샷은 그냥 링크 텍스트로 강등. 굳이 인라인 이미지일 필요 없었음.

# 외부 이미지 카운트 한 줄 체크
grep -oE '!\[.*\]\(https?://[^)]+\)' README.md | wc -l

이걸 PR 단계에서 가드로 거는 것도 검토 중. 10개 넘으면 경고 띄우는 정도로 충분할 듯. 강제하면 배지까지 막혀서 귀찮아짐.

배운 것

문서가 깨지는 건 코드가 깨지는 것보다 발견이 훨씬 늦음. 본인은 브라우저 캐시 덕에 멀쩡한 화면만 보니까, 누가 말해주기 전엔 평생 못 알아챔. 시크릿 창에서 한 번씩 열어보는 습관 들여야 할 듯. 그리고 외부 의존을 자꾸 추가하면 그게 곧 SPOF가 됨. 이미지 한 장도 예외 아님 — 호스팅 도메인 하나 죽으면 문서 인상이 통째로 망가짐.

다음