Tools
README 게시 전 마크다운 미리보기 체크리스트
README, 릴리스 노트, 지원 문서를 공개하기 전에 마크다운 미리보기로 확인할 실무 체크리스트입니다.
검색 의도: 공개 문서가 되기 전에 마크다운 깨짐 확인하기
마크다운은 작성할 때는 단순해 보이지만 공개한 뒤에 문제가 보이는 경우가 많습니다. 제목 단계가 건너뛰어져 있거나, 표가 모바일에서 심하게 밀리거나, 코드 블록 들여쓰기가 깨지거나, 내부 링크가 엉뚱한 페이지를 가리키는 식입니다. 작은 오류지만 README나 지원 문서의 신뢰도를 바로 떨어뜨립니다.
브라우저 마크다운 미리보기는 이 확인을 커밋, 업로드, 고객 답변 전에 끝내게 해줍니다. Sambro의 마크다운 미리보기 도구는 https://tools.sambro.space/ko/tools/markdown-preview 에서 제목, 목록, 코드 블록, 링크를 빠르게 확인할 때 쓸 수 있습니다.
문장 다듬기 전에 구조부터 보기
먼저 목차 흐름을 봅니다. README라면 보통 이 프로젝트가 무엇인지, 누가 써야 하는지, 어떻게 실행하는지, 정상 동작을 어떻게 확인하는지, 도움은 어디서 받는지를 답해야 합니다. 릴리스 노트라면 사용자에게 보이는 변경, 수정 사항, 알려진 이슈를 나눠야 합니다. 미리보기 화면이 긴 문단 덩어리처럼 보인다면 문장보다 제목 구조를 먼저 손봐야 합니다.
여러 사람이 같은 파일을 고칠 때는 제목 단계가 특히 쉽게 흐트러집니다. 페이지 제목은 H1 하나로 두고, H2와 H3를 예측 가능한 순서로 배치합니다. 미리보기만 봐도 문서가 훑어 읽히면 실제 독자의 이해 속도가 빨라집니다.
게시 전 실무 체크리스트
공개하기 전에는 마크다운을 미리보기로 열고 다섯 가지를 봅니다. 제목 순서, 목록 들여쓰기, 표 가독성, 코드 블록 언어 표시, 링크 대상입니다. 문서가 모바일에서 읽힐 가능성이 있다면 좁은 화면에서도 첫 화면과 표를 확인합니다. 데스크톱에서는 괜찮은 표가 지원 문서나 프로젝트 페이지에서는 읽기 어려울 수 있습니다.
코드 예시는 복사하기 쉬운지, 바꿔야 할 값이 분명한지도 봐야 합니다. 치환해야 하는 값은 긴 명령어 중간에 숨기지 말고 명확히 표시합니다. 고객에게 공개되는 문서는 안정적인 공개 URL을 우선하고, 저장소 안에서만 쓰는 문서는 상대 링크가 유지보수에 더 나을 때가 많습니다.
마크다운 미리보기에서 자주 하는 실수
첫 번째 실수는 작성 화면만 믿는 것입니다. 마크다운 원문은 읽을 수 있지만 원문이 읽힌다고 렌더링된 문서까지 읽기 좋은 것은 아닙니다. 두 번째 실수는 초반에 한 번 미리보고 난 뒤 링크, 표, 예시를 고치고 최종 확인을 하지 않는 것입니다.
플랫폼 하나에서만 되는 문법을 많이 쓰는 것도 위험합니다. 문서가 GitHub, 정적 사이트, CMS, 내부 위키를 오갈 수 있다면 문법은 보수적으로 가져가는 편이 안전합니다. 평범한 표, fenced code block, 단순한 목록이 플랫폼 전용 콜아웃보다 오래 살아남습니다.
Sambro 도구 세트 안에서 쓰는 위치
마크다운 미리보기는 작은 게시 전 확인들과 같이 쓰기 좋습니다. 요약문 길이 제한은 글자수 세기로 보고, API 예시가 들어가면 JSON 포맷터로 정리하고, 스크린샷이 무거우면 이미지 압축 도구로 줄입니다. 이런 확인은 https://tools.sambro.space/ko/tools 에서 함께 시작할 수 있습니다.
회사 소개나 서비스 문의 맥락은 https://sambro.space/ 를 기준으로 확인하면 됩니다. 실무 목표는 단순합니다. 문서를 필요로 하는 사람이 보기 전에 먼저 읽히는 상태로 만드는 것입니다.