PDF의 마크다운 코드 블록: 펜스, 긴 줄 및 페이지 분할

코드는 화면에서 완벽해 보이지만 종이로 인쇄할 때 가장 쉽게 깨지는 요소입니다. 넓은 모니터에 맞는 긴 줄이 A4 페이지의 오른쪽 여백을 벗어나거나, 코드 블록이 페이지 하단에 걸쳐 줄이 어색하게 나뉠 수 있습니다.

md2pdf는 펜스 코드 블록을 인쇄 레이아웃의 서식 있는 텍스트로 렌더링합니다. 구문 강조 색상을 강제로 추가하거나 페이지에 맞추기 위해 코드를 임의로 줄 바꿈하지 않습니다. 코드를 변형하면 그 의미가 바뀔 수 있기 때문입니다. 가장 실용적인 방법은 원본 마크다운을 인쇄에 맞게 깔끔하게 정돈하는 것입니다.

이 가이드에서는 코드 블록, 언어 태그, 줄 길이 관리, 테마 선택 및 PDF 출력 전 확인해야 할 사항을 설명합니다. 전체적인 변환 흐름은 GitHub README를 PDF로 변환하는 방법을 참조하십시오.

변환기가 코드 블록을 처리하는 방식

GitHub Flavored Markdown은 3개 이상의 백틱 또는 물결표로 감싼 펜스 코드 블록을 지원합니다. md2pdf는 이러한 펜스를 파싱하여 원본 텍스트를 그대로 유지한 채 <pre><code> 요소로 렌더링합니다. 언어 태그는 클래스 이름으로 유지되지만 현재 렌더러는 별도의 구문 강조 색상을 입히지 않습니다.

이는 다음 두 가지를 의미합니다:

• 들여쓰기, 빈 줄, 구두점이 원본 그대로 보존됩니다.
• 결과물은 색상이 입혀진 토큰 대신 인쇄 테마의 배경과 테두리를 가진 고정폭 텍스트로 표현됩니다.

색상으로 차이점을 설명하는 문서라면 간단한 캡션을 달거나 원본에 + 및 - 기호를 사용하십시오. 인쇄물에서 독자가 색상을 구분할 수 있다고 가정해서는 안 됩니다.

들여쓰기 대신 펜스 코드 블록 사용

4칸 들여쓰기로도 코드 블록을 만들 수 있지만, 펜스 블록이 훨씬 다루기 쉽습니다. 시작과 끝이 명확하고 언어 태그를 지원하며 내부 줄의 들여쓰기에 영향을 받지 않습니다.

기본적인 펜스 코드 블록 예시:

npm install
npm run build
npm test

내부 내용에 포함된 백틱보다 더 많은 백틱을 사용하여 블록을 감싸십시오. 코드 내에 백틱 3개가 포함되어 있다면 4개로 열고 닫아야 합니다.

블록 내에서 탭과 공백을 혼용하지 마십시오. 렌더러는 작성된 그대로를 표시하므로 불규칙한 들여쓰기는 오류처럼 보일 수 있습니다.

색상 강조가 없더라도 언어 태그 지정

구문 색상이 없더라도 언어 태그는 유용합니다. 사용된 언어를 명시하고 에디터와 린터의 처리를 도우며, 번역가에게 번역해서는 안 되는 영역임을 분명히 전달합니다.

자주 쓰이는 태그는 bash, js, ts, json, yaml, python, html, css, sql, text입니다. 터미널 출력이나 로그, 디렉터리 트리에는 text를 사용하십시오.

단순히 도구가 인식한다는 이유로 잘못된 언어 태그를 붙이지 마십시오. 내용의 실제 성격에 맞게 태그를 부여해야 합니다.

인쇄 가능한 너비 내로 줄 길이 유지

인쇄 시 가장 흔한 문제는 페이지 너비보다 긴 코드 라인입니다. 브라우저 미리보기에서는 가로 스크롤이 될 수 있지만 종이에는 스크롤바가 없으므로 글자가 잘리거나 블록 전체가 축소됩니다.

A4 또는 Letter 용지에서는 80~90자 내외가 편안하게 읽을 수 있는 적절한 줄 길이입니다.

줄이 너무 길다면 인쇄 배율을 줄이지 말고 원본 코드를 줄 바꿈하십시오:

const message = buildMessage({ owner, repo, branch, path });

위 코드는 한눈에 읽힙니다. 속성이 더 많다면 여러 줄로 나누어 작성하십시오:

const message = buildMessage({
  owner,
  repo,
  branch,
  path,
});

셸 명령은 백슬래시(\)를 사용하고, 긴 URL은 별도의 줄에 배치하십시오. 목표는 가로 스크롤에 의존하는 줄을 없애는 것입니다.

출력 결과와 로그 처리 방법 결정

터미널 로그나 명령어 출력은 일반 코드보다 너비가 넓고 시간 정보나 경로가 포함되어 있어 줄 바꿈이 어렵습니다.

인쇄에 효과적인 대안:

• 출력 요약. 중요한 행만 보여주고 생략 기호는 본문에 표기하십시오.
• 명령과 출력 분리. 실행 명령과 결과를 별도의 블록으로 분리하십시오.
• 표 형식 활용. 구조화된 데이터라면 고정폭 텍스트보다 마크다운 표가 더 깔끔하게 인쇄됩니다.
• 글꼴 축소는 최후의 수단. 테마 변경은 문서 전체에 영향을 줍니다.

200줄이 넘는 로그 전체를 PDF에 그대로 붙여넣지 마십시오.

테마에 어울리는 코드 스타일 확인

4가지 인쇄 테마는 코드를 다르게 표현합니다. Clean은 밝은 배경과 중립적 서체를 사용하고, Business는 세리프 본문과 대비되는 짙은 코드 블록을 제공합니다. Academic은 본문을 강조하며 Dark 테마는 인쇄 시 가독성을 위해 밝은 잉크 스타일로 자동 전환됩니다.

실용적인 두 가지 권장 사항:

1. 선택한 테마에서 대비 확인. Clean에서 잘 보이던 코드가 Business에서는 무겁거나 Academic에서는 흐릿할 수 있습니다.
2. 인쇄 대화상자에서 배경 그래픽 켜기. 배경 그래픽 옵션을 켜야 코드 블록의 배경색이 온전히 인쇄됩니다.

코드가 많은 문서라면 Clean 테마가 가장 안전합니다. 테마별 상세 비교는 Clean vs Business vs Academic vs Dark를 참고하십시오.

인쇄된 PDF 최종 검토

생성된 PDF를 열어 모든 코드 블록을 세밀하게 확인하십시오:

• 오른쪽 여백 잘림 여부. 오른쪽 여백에서 코드가 중간에 잘리지 않았는지 확인합니다.
• 페이지 하단 단절. 블록의 첫 줄만 페이지 하단에 외롭게 남지 않도록 합니다.
• 들여쓰기 일관성. 공백과 탭이 의도대로 유지되었는지 점검합니다.
• 빈 줄 보존 여부. 논리적 구분을 위한 빈 줄이 유지되었는지 확인합니다.
• 흑백 인쇄 대비. 흑백 복사를 고려하여 명암을 점검합니다.
• 설명 본문 명시. 언어 구분이 중요하다면 본문 설명에도 해당 언어를 표기하십시오.

문서를 널리 공유할 계획이라면 다른 브라우저에서도 인쇄 결과를 테스트해보는 것이 좋습니다.

코드 블록은 독자가 가장 많이 복사하고 재사용하는 핵심 영역입니다. 너비를 준수하고 간결하게 작성하십시오. 브라우저 내부 변환 원리에 대한 자세한 정보는 브라우저 단독 마크다운 PDF 변환을 확인하십시오.