README는 브라우저를 기준으로 쓰인 문서입니다. 스크롤되고, 외부로 링크되며, 독자가 저장소를 클릭해 둘러볼 수 있다고 전제합니다. 하지만 문서를 고객에게 보내야 하거나, 과제에 첨부해야 하거나, 릴리스를 보관해야 하거나, 저장소를 복제하지 않을 사람에게 건네야 하는 순간에는 PDF가 가장 멀리까지 가는 형식입니다.
GitHub 페이지를 그대로 인쇄하면 보통 엉망이 됩니다. 사이트 탐색, 사이드바, 바닥글까지 함께 따라옵니다. 넓은 코드 블록은 잘리고, 브라우저가 더 이상 저장소 루트에서 읽지 않기 때문에 상대 이미지가 깨집니다. 긴 표는 페이지 중간에서 어색하게 나뉩니다. md2pdf는 계정을 만들거나 원본 파일을 서버에 업로드하도록 요구하지 않고 바로 이런 문제들을 해결하기 위해 만들어졌습니다.
이 가이드는 저장소 URL을 붙여넣는 것부터 내보낸 PDF를 점검하는 것까지 전체 흐름을 안내하고, 각 단계에서 도구가 무엇을 하는지 설명합니다.
브라우저의 인쇄 버튼만으로는 부족한 이유
GitHub의 웹 인터페이스는 인쇄 스타일시트가 아니라 웹 앱입니다. 저장소 페이지에서 Ctrl+P를 누르면 브라우저는 헤더, 파일 트리, “About” 사이드바, 피드백 위젯, 그리고 레이아웃에 있는 나머지 요소까지 페이지 전체를 인쇄하려고 합니다. 일부는 사용자 지정 인쇄 스타일시트로 숨길 수 있지만, 외부에서 GitHub의 마크업을 바꿀 수는 없습니다.
그 밖에도 자주 반복되는 문제가 세 가지 있습니다:
- 상대 이미지 경로.
라고 적힌 README는 이미지가 저장소를 기준으로 해석되기 때문에 GitHub에서 제대로 보입니다. 인쇄된 브라우저 페이지에는 저장소 컨텍스트가 없으므로 이미지가 사라질 수 있습니다. - 넓은 코드와 표. 코드 블록과 비교 표는 인쇄 페이지보다 넓습니다. 인쇄 전용 규칙이 없으면 읽을 수 없을 만큼 축소되거나 잘립니다.
- 페이지 나눔. 제목, 코드 블록, 표 행은 어색한 나눔을 피해야 합니다. 브라우저의 기본 인쇄는 이런 부분을 잘 처리하지 못합니다.
md2pdf는 README의 원본 Markdown을 가져와 저장소 기준 상대 URL을 해석하고, GitHub Flavored Markdown으로 렌더링한 뒤 결과를 정화하고, 브라우저의 인쇄 대화상자가 열리기 전에 인쇄 스타일시트를 적용합니다. 출력은 여전히 브라우저의 기본 “PDF로 저장” 엔진이 만들지만, 그 엔진이 받는 문서는 이미 정리된 상태입니다.
md2pdf가 바꾸는 것
변환 파이프라인은 전부 브라우저에서 실행됩니다. 실제로는 다음과 같습니다:
- 공개 GitHub 저장소 URL, 로컬 Markdown 파일 또는 붙여넣은 Markdown을 제공합니다.
- 저장소인 경우 앱이 기본 브랜치를 찾고,
.github/안의 파일을 포함해 일반적인 README 파일명들을 시도합니다. - 상대 이미지 경로는
raw.githubusercontent.com으로, 문서 링크는 GitHub blob 보기로 다시 작성됩니다. - Markdown은 GFM 지원과 함께 렌더링됩니다. 표, 작업 목록, 취소선, 펜스 코드, 자동 링크가 포함됩니다.
- HTML은 미리보기에 도달하기 전에 DOMPurify로 정화됩니다.
- 문서에 제목이 세 개 이상 있으면 목차가 생성됩니다.
- 선택한 테마의 인쇄 스타일시트가 적용되고 브라우저가 인쇄 대화상자를 엽니다.
어떤 파일도 업로드되지 않습니다. 외부로 나가는 요청은 요청한 공개 저장소를 익명으로 읽는 것과 기본 브랜치를 찾기 위한 GitHub API 호출뿐입니다. 이 버전에서는 비공개 저장소를 지원하지 않습니다.
시작하기 전에
필요한 것:
- 공개 GitHub 저장소, 또는 로컬 Markdown 파일, 또는 붙여넣을 수 있는 Markdown 텍스트.
- 최신 브라우저. Chrome, Edge, Firefox, Safari 모두 인쇄 대화상자에서 “PDF로 저장”을 지원합니다.
- 짧은 문서라면 약 2분, PDF를 페이지별로 검토할 계획이라면 그보다 더 많은 시간.
저장소가 비공개라면 가져오기가 실패합니다. 수동 대체 방법은 여전히 유효합니다. README 텍스트를 복사해 편집기에 붙여넣고 절대 이미지 URL을 사용하세요.
1단계: 도구에 저장소 알려주기
변환기를 열고 GitHub 저장소 URL 필드에 저장소 URL을 붙여넣으세요. md2pdf는 정규 URL 외에도 여러 형식을 받습니다:
https://github.com/owner/repo
https://github.com/owner/repo.git
github.com/owner/repo
owner/repo
https://github.com/owner/repo/tree/main/docs
https://github.com/owner/repo/blob/main/README.md이 URL들은 모두 같은 owner/repo 조합으로 해석됩니다. 프로토콜이 없는 URL과 owner/repo 축약형은 터미널이나 채팅 메시지에서 복사할 때 편리합니다. 편의를 위해 추가 경로 세그먼트도 허용되지만 무시됩니다. 앱은 URL에 표시된 하위 파일이 아니라 기본 브랜치의 저장소 루트 README를 읽습니다. 하위 파일이 필요하다면 해당 Markdown을 직접 붙여넣으세요.
가져오기를 누르거나 Enter를 입력하세요. 필드가 비어 있으면 앱은 아무 반응 없이 넘어가지 않고 무엇을 기대하는지 알려줍니다.
2단계: README 가져오기와 경로 해석
앱은 먼저 GitHub API에 저장소의 기본 브랜치를 묻습니다. 그다음 해당 브랜치를 기준으로 일반적인 대소문자 변형과 .github/README.md 위치를 포함한 README 파일명 목록을 시도합니다. API가 요청 한도에 걸려도 원본 가져오기는 계속될 수 있기 때문에, 일시적인 API 실패가 항상 작업 흐름을 끝내지는 않습니다.
Markdown이 도착하면 미리보기가 업데이트됩니다. 이때 세 가지를 확인하세요:
- 이미지. 저장소 기준 상대 이미지가 나타나야 합니다. 나타나지 않는다면 비공개 자산, 존재하지 않는 경로, 또는 핫링크를 차단하는 절대 URL을 가리킬 수 있습니다.
- 코드 블록. 언어가 지정된 펜스는 코드로 렌더링됩니다. 아주 넓은 줄은 미리보기에서 스크롤되지만, 인쇄 시에도 확인이 필요합니다.
- 링크. 문서 링크는 PDF에서도 의미가 남도록 GitHub blob 보기로 다시 작성됩니다. 외부 링크는 미리보기에서 새 탭으로 열립니다.
이미지가 실패하면 md2pdf는 깨진 이미지로 표시하고 계속 진행합니다. 배지 하나를 불러오지 못했다고 내보내기 전체가 실패하지는 않습니다. 이는 의도된 동작입니다. 빠진 배지는 보통 문서의 나머지보다 덜 중요합니다.
3단계: 문서에 맞는 테마 선택
인쇄 테마는 네 가지입니다:
- Clean이 기본값입니다. 중립적인 산세리프 서체를 사용하며 명세서, 기술 README, 코드가 많은 문서에 가장 안전한 선택입니다.
- Business는 세리프 서체와 어두운 코드 블록을 사용합니다. 보고서, 제안서, 고객 전달 문서에 어울립니다.
- Academic은 밝은 코드 처리를 곁들인 양쪽 정렬 세리프 페이지를 사용합니다. 장문의 글, 강의 자료, 논문 형태의 제출물을 위해 만들어졌습니다.
- Dark는 화면 우선 테마입니다. 미리보기는 편안한 읽기를 위해 어둡고, 인쇄 스타일시트는 PDF가 읽기 좋게 유지되도록 밝은 잉크와 밝은 코드 배경을 강제합니다.
더 자세한 비교는 Clean vs Business vs Academic vs Dark에서 확인하세요. 대부분의 첫 내보내기에서는 Clean으로 시작하고, 문서에 뚜렷한 독자 기대가 있을 때만 바꾸는 것이 좋습니다.
4단계: 목차가 도움이 될지 판단하기
자동 목차는 기본으로 켜져 있으며 문서에 제목이 세 개 이상일 때 생성됩니다. 안정적이고 고유한 제목 슬러그를 사용하므로 미리보기에서 각 항목이 올바른 섹션으로 연결됩니다.
다음 경우에는 켜 두세요:
- 문서가 몇 페이지보다 길 때.
- 독자가 특정 섹션으로 바로 이동해야 할 때.
- PDF를 일부만 인쇄할 수도 있는 사람에게 건넬 때.
다음 경우에는 끄세요:
- README가 짧아서 목차 블록이 탐색보다 잡음이 더 될 때.
- 문서에 이미 직접 작성한 목차가 있을 때.
- 한 페이지짜리 유인물을 만들 때.
이 토글은 미리보기와 인쇄 출력 모두에 영향을 줍니다. PDF에만 적용되는 별도 설정은 없습니다.
5단계: 올바른 설정으로 PDF 인쇄
실시간 미리보기 패널에서 PDF 다운로드 / 인쇄를 클릭하세요. 앱이 브라우저의 인쇄 대화상자를 엽니다. 대화상자에서:
- 대상을 PDF로 저장(또는 브라우저의 해당 항목)으로 설정합니다.
- 받는 사람의 지역에 맞춰 A4 또는 Letter를 선택합니다.
- 사내 표준이 없다면 여백은 기본값으로 두세요. 인쇄 스타일시트가 이미 페이지 여백을 설정합니다.
- 첫 시도에서는 배율을 100%로 유지하세요. 넓은 표나 코드 블록이 잘리면 원본의 글꼴을 줄이지 말고 배율을 조금 낮추세요.
- 브라우저에 해당 옵션이 있다면 배경 그래픽을 켜세요. 테마 강조색, 코드 블록 배경, 표 헤더 채우기는 배경색에 의존합니다. 없어도 PDF는 읽을 수 있지만 Business와 Dark는 시각적 구조를 일부 잃습니다.
- URL과 페이지 번호가 꼭 필요하지 않다면 브라우저의 머리글 및 바닥글을 끄세요. 이는 문서 디자인의 일부가 아닙니다.
owner-repo-readme-2026-10.pdf처럼 내용을 알 수 있는 이름으로 파일을 저장하세요.
정확한 레이블은 브라우저마다 다릅니다. Chrome과 Edge에서는 배경 그래픽이 “고급 설정” 아래에 있습니다. Firefox에서는 “배경 인쇄”를 찾으세요. Safari는 제공하는 제어 항목이 더 적으니 저장 전에 미리보기를 확인하세요.
6단계: 보내기 전에 PDF 점검
저장한 PDF를 열고 인쇄에서 드러나는 문제들을 살펴보세요:
- 페이지 나눔. 제목이 페이지 맨 아래에 홀로 남지 않아야 합니다. 코드 블록, 표, 이미지는 중간에서 나뉘지 않아야 합니다.
- 넓은 콘텐츠. 긴 코드 줄과 표가 가장 흔한 넘침 원인입니다. 잘렸다면 원본에서 줄을 줄이거나 인쇄 배율을 낮추세요.
- 링크. PDF의 링크 몇 개를 클릭해 보세요. GitHub blob 링크는 올바른 파일 보기를 열어야 합니다.
- 이미지. 다이어그램과 배지가 살아남았는지 확인하세요. 빠진 비공개 자산은 PDF에서 저절로 고쳐지지 않습니다.
- 메타데이터. 문서 제목과 작성자는 전용 PDF 메타데이터 양식이 아니라 README와 브라우저의 인쇄 메타데이터 설정에서 옵니다. 파일 이름을 명확히 지으세요.
- 가독성. 페이지를 100%로 인쇄해 본문이 편안한지 확인하세요. Academic의 양쪽 정렬 텍스트와 Business의 세리프 서체는 화면과 종이에서 다르게 보일 수 있습니다.
가져오기에 실패했을 때
앱은 가져오기 실패를 실행 가능한 메시지로 바꿔 보여줍니다. 흔한 경우는 다음과 같습니다:
| 표시되는 내용 | 보통 의미하는 것 | 해야 할 일 |
|---|---|---|
| 저장소를 찾을 수 없거나 비공개 | URL이 잘못되었거나 저장소에 인증이 필요함 | URL을 확인하고, 비공개 저장소라면 Markdown을 직접 붙여넣기 |
| README를 찾을 수 없음 | 기본 브랜치, main, master에 README가 없음 |
파일을 업로드하거나 Markdown을 붙여넣기 |
| GitHub 요청 한도 도달 | 인증되지 않은 API 요청이 너무 많음 | 약 1분 기다린 뒤 재시도. 원본 가져오기는 여전히 동작할 수 있음 |
| 가져오기 실패 또는 시간 초과 | 네트워크 문제 또는 15초 제한 시간 초과 | 재시도. 수동 붙여넣기 경로는 여전히 유효 |
가져오기에 실패해도 편집기는 이미 입력한 내용을 그대로 유지합니다. 페이지를 잃지 않고 붙여넣기나 업로드 모드로 전환할 수 있습니다.
대신 붙여넣거나 업로드하기
GitHub 가져오기는 편리하지만 유일한 방법은 아닙니다. 변환기는 다음도 지원합니다:
- 최대 2MB의
.md,.markdown,.txt파일 업로드. - Markdown을 편집기에 직접 붙여넣기. 입력하는 동안 짧은 디바운스 후 미리보기가 다시 렌더링됩니다.
- 표, 작업 목록, 코드 블록이 어떻게 처리되는지 보려면 샘플 불러오기.
한 가지 주의할 점: 상대 이미지 경로는 저장소를 먼저 가져온 경우에만 해석됩니다. 업로드하거나 붙여넣은 Markdown에는 저장소 기준 경로가 없으므로 그 모드에서는 절대 이미지 URL을 사용하세요. 제목, 표, 코드, 작업 목록 등 나머지는 모두 동일하게 동작합니다.
모든 내보내기를 개선하는 원본 수준의 다섯 가지 수정
PDF의 품질은 출발점인 Markdown을 넘어설 수 없습니다. 다음 변경은 즉시 효과를 냅니다:
- 실제 제목 계층을 사용하세요. 섹션은
##로 시작하고 하위 섹션에는###를 사용하며, 단계를 건너뛰지 마세요. 목차와 인쇄 스타일시트 모두 구조에 의존합니다. - 이미지에 유용한 대체 텍스트를 넣으세요. 접근성에도 좋고, 이미지를 불러오지 못할 때 PDF에 읽을 수 있는 대체 내용을 제공합니다.
- 코드에는 언어를 지정해 펜스를 사용하세요. 언어가 지정된 블록은 들여쓰기 코드보다 예측 가능하게 렌더링되며, 특히 줄이 길 때 그렇습니다.
- 표는 좁게 유지하세요. 열이 여덟 개인 표는 축소하지 않고는 A4에 맞지 않습니다. 세부 내용은 본문으로 옮기거나 표를 나누세요.
- 저장소 자산에는 상대 경로를 선호하세요. md2pdf가 이를 올바르게 다시 작성합니다. 로컬 머신이나 비공개 버킷을 가리키는 절대 링크는 이동 과정에서 살아남지 못합니다.
개인정보: 브라우저를 떠나는 것
md2pdf는 Markdown을 업로드하지 않습니다. 렌더링, 정화, 목차 생성, PDF 내보내기가 모두 로컬에서 이루어집니다. 저장소를 가져올 때 외부로 나가는 요청은 공개 README와 그 이미지를 GitHub에서 익명으로 읽는 것뿐입니다. 계정도, 쿠키도, 변환 과정에 연결된 분석 도구도 없습니다.
문서에 내부 메모, 고객 이름, 미공개 계획이 담겨 있을 때 이 점이 중요합니다. 민감한 Markdown을 붙여넣고 제3자 변환 서비스에 텍스트를 보내지 않고 내보낼 수 있습니다. 로컬 파일도 마찬가지입니다. 파일은 업로드되지 않고 브라우저가 읽습니다.
요약
공개 저장소 URL을 붙여넣고 가져오기를 누른 뒤 미리보기를 확인하고, 테마를 고르고, 긴 문서라면 목차를 켜 둔 상태에서 배경 그래픽을 켜고 PDF로 인쇄하세요. 파일을 보내기 전에 페이지 나눔과 넓은 코드 블록을 확인하세요. 가져오기에 실패하면 Markdown을 붙여넣거나 업로드해 계속 진행하세요.
전체 흐름은 지루할 정도로 단순하게 설계되었습니다. 계정도, 대기열도, 업로드도, 서버 측 렌더러도 없습니다. README 하나, 인쇄 스타일시트 하나, 그리고 누군가에게 건넬 수 있는 PDF 하나뿐입니다.
나만의 README PDF 만들기
무료이고 로그인이 필요 없으며, 모든 처리가 클라이언트에서 이루어집니다.