README·PR 설명용 마크다운, 올리기 전에 브라우저에서 미리보는 방법

README·PR 설명용 마크다운, 올리기 전에 브라우저에서 미리보는 방법

개발자라면 README나 PR 본문을 마크다운으로 작성하는 일이 일상입니다.

문제는 로컬 에디터에서 볼 때랑 GitHub에 올렸을 때 렌더링이 미묘하게 다르다는 점입니다.

특히 표, 코드펜스, 체크리스트를 섞으면 "로컬에선 괜찮았는데 PR에선 깨짐"이 자주 납니다.

문제 상황

예를 들어 이런 경우가 있습니다.

• VS Code 미리보기와 GitHub flavored markdown 차이
• Notion에서 복사한 내용이 GitHub에선 표가 깨짐
• ChatGPT가 짜 준 API 스펙을 README에 붙였더니 제목 단계가 이상함

매번 브랜치 올려서 확인하기엔 사이클이 깁니다.

해결 방향

저는 "커밋 전에 브라우저에서 한 번 렌더 확인"을 습관으로 두고 있습니다.

별도 설치 없이 쓸 수 있는 마크다운 뷰어로 이 페이지를 씁니다.

→ MarkdownHub 마크다운 뷰어

특징만 정리하면 다음과 같습니다.

• GitHub / Notion / Classic 스타일 미리보기
• 표·코드블록 확인이 빠름
• Word / Google Docs로 서식 유지 복사 가능 (스펙 문서를 기획/PM에게 넘길 때 유용)
• 브라우저 로컬에서만 처리 (README에 토큰·내부 URL이 있어도 서버 업로드 부담이 적음)

추천 워크플로

1. README 초안을 에디터에서 작성
2. 전체를 뷰어에 붙여넣고 GitHub 스타일로 확인
3. 깨진 표·상대경로 이미지·헤딩 단계만 수정
4. 그다음 커밋 / PR

완벽히 GitHub과 1:1은 아니지만, "올렸다가 다시 amend"하는 횟수는 확실히 줄었습니다.

Flutter나 안드로이드 모듈 README처럼 표가 많은 문서일수록 효과가 큽니다.

다음 글에서는 ChatGPT가 만든 마크다운 스펙을 문서용으로 정리할 때 제가 쓰는 체크리스트도 정리해보겠습니다.