중첩된 글머리 기호, 코드 블록 몇 개, 두 가지 접근 방식을 비교하는 표가 있는 README를 작성합니다. 에디터에서 순수 텍스트로 보면 괜찮아 보입니다. 그런데 GitHub에 푸시하니 표가 정렬이 어긋나 있고, 코드 블록 하나가 제대로 닫히지 않았으며, 어느 지점에서 우연히 들어간 빈 줄 때문에 번호 목록이 중간에 1부터 다시 시작합니다. 이제 포맷팅을 바로잡기 위해 작은 수정 커밋을 계속 올리고 있습니다.
마크다운은 기본적인 포맷팅이라면 기억만으로 작성할 수 있을 만큼 단순하지만, 표, 중첩 목록, 코드 펜스는 렌더러마다 미묘하게 다른 구문상의 특이점을 가지고 있습니다. GitHub Flavored Markdown은 CommonMark와 똑같지 않고, CommonMark도 정적 사이트 생성기가 쓰는 것과 똑같지 않습니다. "머릿속에서는 맞아 보인다"와 "페이지에서 제대로 렌더링된다" 사이의 간극이야말로 실시간 미리보기가 진가를 발휘하는 지점입니다.
커밋으로 확인하는 것이 나쁜 워크플로인 이유
README가 어떻게 렌더링되는지 보기 위해 커밋을 푸시하고, 깨진 표를 고치기 위해 또 하나를 푸시하고, 그 수정을 또 수정하기 위해 하나를 더 푸시하는 것은 실제 콘텐츠와 무관한 포맷팅 노이즈로 커밋 히스토리를 어지럽힙니다. 또한 미리보기 주기마다 푸시와 페이지 새로고침만큼의 시간이 걸린다는 뜻이기도 합니다 — 너무 느려서 확인을 아예 포기하고 괜찮기를 바라게 됩니다.
입력하는 즉시 렌더링된 결과 보기
Bellows는 원시 마크다운을 붙여넣거나 입력하는 대로 포맷된 결과를 렌더링해 주는 마크다운 미리보기 도구를 포함합니다. 헤더, 목록, 표, 링크, 코드 블록이 모두 즉시 렌더링되므로 포맷팅 실수를 커밋에 담기 전에 잡아낼 수 있습니다.
README와 PR 설명 작성하기
풀 리퀘스트 설명과 README 파일은 종종 리뷰어나 신규 기여자가 가장 먼저 읽는 것입니다. 제출하기 전에 헤더, 체크리스트, 링크된 이미지가 올바르게 렌더링되는지 확인하면 "포맷팅 좀 고쳐주세요"라는 댓글 한 라운드를 아낄 수 있습니다.
오프라인으로 문서 작성하기
비행기 안이나 인터넷이 불안정한 곳에서 문서를 작성한다고 해서 포맷팅이 제대로 렌더링되는지 확인하는 것을 포기할 필요는 없습니다. 로컬 미리보기 도구는 연결 여부와 상관없이 동일하게 작동합니다.