## 개발자 워크플로

Mac에서 GitHub README.md 로컬 미리보기 방법

2026년 3월 게시

README를 수정했습니다. 이제 push하기 전에 어떻게 보이는지 확인하고 싶으시죠. 무거운 방법부터 즉시 확인까지, 세 가지 방법을 소개합니다.

## 왜 로컬에서 미리보기?

왜 로컬에서 미리보기해야 할까요?

  • push 전에 서식을 확인하세요. 깨진 표, 잘못된 링크, 엉킨 코드 블록은 공개 저장소에서 당혹스럽습니다. git push 전에 잡으세요.
  • 오프라인 작업. 비행기, 기차, Wi-Fi가 불안정한 카페. README 확인에 인터넷 연결이 필요해서는 안 됩니다.
  • PR 문서 변경 사항 검토. 풀 리퀘스트에서 README가 업데이트될 때, 코드 diff와 함께 렌더링된 결과를 확인하고 싶을 것입니다.
  • 커밋-푸시-확인 반복을 피하세요. README가 GitHub에서 어떻게 보이는지 확인하기 위해 커밋을 push하면 git 히스토리가 오염되고 시간이 낭비됩니다.

## 방법 1

grip (CLI 도구)

pip install grip
grip README.md

grip은 GitHub API를 사용하여 Markdown을 렌더링하므로, 브라우저에서 localhost:6419에서 GitHub과 동일한 렌더링을 볼 수 있습니다.

장점

  • 정확한 GitHub 렌더링 (GitHub API 사용)

단점

  • Python 설치 필요
  • 많이 사용하면 GitHub API 토큰 필요 (미사용 시 속도 제한)
  • 시작하고 중지해야 하는 로컬 서버 실행
  • 오프라인 비친화적 (GitHub API 호출 필요)

## 방법 2

VS Code 내장 미리보기

VS Code에서 README.md 열기
Cmd + Shift + V → 미리보기 패널

VS Code에는 내장 Markdown 미리보기가 있습니다. 파일을 열고 키보드 단축키를 누르면 사이드 패널에 렌더링된 결과가 표시됩니다.

장점

  • 대부분의 개발자에게 이미 설치되어 있음
  • 오프라인 작동

단점

  • README 미리보기를 위해 전체 IDE를 실행하는 것은 과함
  • 미리보기 렌더링이 GitHub과 정확히 일치하지 않음 (콜아웃 미지원, 다른 표 스타일)
  • 에디터에 종속 — 파일을 더블클릭만으로 열 수 없음

## 방법 3 (추천)

ShowMeMyMD — 더블클릭만 하세요

git clone <repo>
README.md 더블클릭
끝.

ShowMeMyMD는 네이티브 macOS Markdown 뷰어입니다. .md 파일의 기본 앱으로 설정하면 모든 README가 즉시 렌더링된 미리보기로 열립니다. CLI도 서버도 설정도 필요 없습니다.

GitHub-Flavored Markdown 완벽 지원:

  • 정렬이 포함된 표
  • 체크박스가 있는 작업 목록
  • 구문 강조가 적용된 펜스형 코드 블록
  • GitHub 스타일 콜아웃: NOTE, TIP, WARNING, IMPORTANT, CAUTION

클론하고, README.md 더블클릭하면, 끝.

## 비교

나란히 비교

도구설정GFM 정확도속도오프라인
gripPython + pip 설치정확 (GitHub API)느림 (네트워크)불가
VS Code이미 설치됨부분적빠름가능
ShowMeMyMDMac App Store에서 한 번 설치GFM + 콜아웃 완벽 지원즉시가능

## 더 읽기

Mac용 Markdown 뷰어 ShowMeMyMD에 대해 더 알아보세요. 개발자 워크플로에 어떻게 적용되는지 확인하세요. 또는 GitHub 스타일 콜아웃 가이드를 읽어보세요.

README 확인을 위한 push는 이제 그만

아무 .md 파일이든 더블클릭하면 즉시 렌더링됩니다. GitHub-Flavored Markdown, 구문 강조, 4가지 테마. Mac App Store에서 $2.99.

다운로드:Mac App Store