표는 기술 문서에서 독자가 가장 먼저 찾는 핵심 정보입니다. 하지만 마크다운을 PDF로 변환할 때 가장 먼저 어긋나는 요소이기도 합니다. 넓은 브라우저 창에서는 완벽해 보이던 열들이 A4 용지에서는 답답하게 압축되고 긴 셀 텍스트가 여백을 침범합니다.
md2pdf는 GitHub Flavored Markdown 표를 렌더링하여 인쇄 스타일시트 및 A4 PDF 렌더러로 전달합니다. 도구가 표의 가독성을 최대한 보존하지만 없는 여백을 만들어낼 수는 없습니다. 가장 중요한 작업은 마크다운 원본에서 필수 열을 정하고 셀 내용을 간결하게 줄이는 것입니다.
이 가이드에서는 원본 작성 단계의 최적화와 인쇄 전 필수 검토 항목을 설명합니다. 전체 변환 프로세스는 GitHub README를 PDF로 변환하는 방법을 참조하십시오.
인쇄 시 표가 깨지는 근본적인 이유
브라우저 화면의 표는 유연합니다. 화면을 벗어나면 가로 스크롤을 제공하거나 텍스트를 줄일 수 있습니다. 반면 인쇄된 종이는 고정된 폭을 가지며 스크롤바가 없습니다. 내용이 페이지 폭보다 넓으면 표가 잘리거나 글자가 너무 작아져 읽을 수 없게 됩니다.
문제를 악화시키는 세 가지 원인:
- 지나치게 많은 열. 좁은 8개 열보다 명확한 4개 열이 훨씬 읽기 쉽습니다.
- 셀 내부의 장문 문단. 셀 안에 여러 문장이 들어가면 표 본연의 빠른 탐색 기능을 상실합니다.
- 줄 바꿈 없는 코드나 긴 URL. 공백 없는 긴 단어 하나가 전체 열의 최소 너비를 불필요하게 늘립니다.
해결책은 글자 크기를 줄이는 것이 아니라 표의 역할을 단순화하는 것입니다.
폭에 꼭 맞는 표로 시작하기
유용한 표는 목적이 하나이고 열 수가 적습니다. 다음 예시는 모든 CSS 속성을 나열하는 대신 인쇄 테마의 핵심 차이점을 깔끔하게 비교합니다:
| Setting | Clean | Business | Academic |
| --- | :--- | :--- | ---: |
| Body type | Sans | Serif | Justified serif |
| Best for | Specs | Reports | Course readers |
| Tone | Neutral | Formal | Editorial |이 표는 A4와 Letter 규격에 여유 있게 들어맞으며 짧은 셀 텍스트 덕분에 다국어 번역 시에도 레이아웃이 유지됩니다. :--- 왼쪽 정렬, :---: 가운데 정렬, ---: 오른쪽 정렬입니다.
정렬은 장식이 아닌 의미 전달을 위해 사용하십시오. 숫자는 오른쪽 정렬, 짧은 라벨은 왼쪽 정렬이 자연스럽습니다.
데이터 나열이 아닌 해결할 질문에 따라 열 선택
열을 추가하기 전에 표가 어떤 질문에 답하고 있는지 자문해 보십시오. 마이그레이션 표라면 ’무엇이 변경되었고 어떻게 조치해야 하는가?’에 답해야 하며 변경 항목, 변경 내용, 조치 사항 3개 열이면 충분합니다. 12개 필드를 모두 담은 데이터베이스 덤프는 PDF 표에 어울리지 않습니다.
표의 헤더 행을 소리 내어 읽어보십시오. 자연스러운 비교 문장을 형성하지 못한다면 정보가 과도하게 담긴 것입니다.
폭이 넓은 참조 데이터의 경우 2열 정의 목록 형식을 고려하십시오:
| Field | Meaning |
| --- | --- |
| `owner` | GitHub user or organization |
| `repo` | Repository name without the host |
| `ref` | Branch, tag, or commit SHA |이러한 2열 형식은 다열 표보다 인쇄와 번역 모두에 훨씬 유리합니다.
셀 내용은 짧고 빠르게 스캔할 수 있도록 작성
표는 정보 비교를 위한 것이지 긴 설명을 위한 공간이 아닙니다. 두 문장 이상의 설명이 필요하다면 표 아래 본문으로 옮기고 셀에는 핵심 요약만 남기십시오.
실용적인 작성 원칙:
- 명사형이나 간결한 문구 사용. ‘공개 저장소 필요’ 정도로 충분합니다.
- 단위는 헤더에 명시. 행마다 ’MB’를 반복하지 말고
용량 (MB)으로 작성하십시오. - 셀 내부 강제 줄 바꿈 지양.
<br>태그는 페이지 넘김을 부자연스럽게 만듭니다. - 링크 텍스트 축약. 전체 URL 대신 짧은 링크 라벨을 사용하십시오.
- 색상 의존 탈피. 흑백 인쇄 환경을 고려해야 합니다.
셀에 긴 명령어가 들어가야 한다면 표 하단에 별도 코드 블록을 두고 이름으로 참조하십시오.
내보내기 전 넓은 데이터 재구성
열을 줄일 수 없는 넓은 표라면 문서의 구조를 바꾸어야 합니다:
- 독자별 분리. 운영자용 표와 개발자용 표를 별도로 분리하십시오.
- 버전별 분리. 수십 개 릴리스 기록은 메이저 버전별로 표를 나눕니다.
- 행과 열 전환. 항목이 적고 속성이 많다면 속성을 행으로, 항목을 열로 배치하여 세로형 표로 만듭니다.
- 목록 형태로 전환. 빈 셀이 많다면 소제목과 글머리 기호 목록이 훨씬 명확합니다.
재구성 후 공백 없는 긴 URL이나 긴 식별자가 열 너비를 강제하고 있지 않은지 다시 점검하십시오.
페이지 분할과 헤더 반복 출력 확인
한 페이지에 들어맞던 표도 여러 페이지에 걸쳐 인쇄될 때 문제가 발생할 수 있습니다. 헤더가 반복 표시되어야 하며 행 중간에서 텍스트가 잘리지 않아야 합니다.
브라우저 인쇄 엔진과 도서 PDF 렌더러는 페이지 분할을 다르게 처리합니다. 표가 여러 페이지에 걸쳐 이어진다면 표 상단에 열 구성을 안내하는 캡션을 달아주는 것이 좋습니다.
인쇄 내보내기 전 체크리스트
인쇄하거나 내보내기 전 다음 사항을 점검하십시오:
- 표가 명확한 단일 목적을 가지며 열 수가 5~6개 이하인가?
- 헤더가 간결하며 단위가 포함되어 있는가?
- 셀 내용이 문단이 아닌 요약 문구로 작성되었는가?
- 전체 URL이나 페이지 너비를 넘는 긴 단어가 없는가?
- 숫자와 라벨에 적절한 정렬이 적용되었는가?
- 페이지를 넘어갈 경우를 대비한 설명 캡션이 있는가?
- 화면 미리보기뿐 아니라 실제 저장된 PDF 파일을 열어 확인했는가?
테마별 세부 특징은 Clean vs Business vs Academic vs Dark를 확인하십시오.
표는 복잡하고 화려할 필요가 없습니다. 인쇄된 종이 위에서 한눈에 정보를 파악할 수 있는 간결한 표가 항상 최선의 결과를 만들어냅니다.
나만의 README PDF 만들기
무료이고 로그인이 필요 없으며, 모든 처리가 클라이언트에서 이루어집니다.