마크다운 상대 경로 이미지와 문서 간 링크의 PDF 변환 및 해결 방법

코드 저장소에 저장된 마크다운 문서들은 상대 경로를 적극적으로 사용합니다. 아키텍처 다이어그램은 ./assets/diagram.png에 있고, 화면 캡처는 ../images/screen.jpg에 위치하며, 다른 문서 링크는 ./getting-started.md를 가리킵니다. 변환 도구가 저장소의 디렉터리 경로를 계산하지 못하면 이미지가 깨지고 링크가 작동하지 않습니다. md2pdf는 상대 경로를 정확하게 추적하여 고해상도 이미지와 유효한 링크를 PDF에 완벽히 담아냅니다.

이 글에서는 md2pdf의 상대 경로 파싱 원리, 브라우저 기반 이미지 페칭 방식, 문서 간 파일 링크를 PDF 내부 북마크로 전환하는 기술을 다룹니다.

정적 마크다운에서 상대 경로가 유발하는 문제

마크다운 파일은 로컬 파일 시스템이나 웹 저장소 인터페이스에서 함께 존재하는 폴더 구조를 전제로 작성됩니다:

• 깨진 이미지 박스: ![아키텍처](images/arch.png)와 같은 상대 경로는 상위 폴더 정보 없이는 로딩에 실패합니다.
• 먹통이 되는 파일 링크: 다른 문서를 가리키는 [설치 가이드](setup.md) 링크는 단일 PDF로 변환될 때 연결이 끊어집니다.
• 상위 디렉터리 탐색: ../ 경로를 계산하려면 파일 트리의 위치를 수학적으로 역추적해야 합니다.

Relative Path Resolution Matrix:
Base Document:  docs/guides/installation.md
Image Path:     ../assets/diagram.png
Resolved Asset: docs/assets/diagram.png (Fetched & Inlined)

Link Path:      ./configuration.md
Resolved Link:  Internal PDF Anchor -> Chapter: Configuration

GitHub 저장소의 이미지 리소스 추출 및 해결

GitHub에서 문서를 가져올 때 md2pdf는 각 마크다운 파일의 디렉터리 깊이를 기록합니다:

1. 경로 표준화: ../../images/flow.png와 같은 상대 경로를 현재 파싱 중인 파일의 위치를 기준으로 계산합니다.
2. 클라이언트 직수신: md2pdf는 GitHub 콘텐츠 배포망(CDN)의 원본 이미지 주소를 조합하여 브라우저로 직접 내려받습니다.
3. 인메모리 바이너리 변환: 수신된 이미지는 브라우저 메모리상에서 바이너리 버퍼로 변환된 후 pdf-lib를 통해 PDF 내부로 직접 임베드됩니다.
4. 포맷 지원: PNG, JPEG, WebP, SVG 등 널리 쓰이는 웹 이미지 형식을 본래 가로세로 비율에 맞춰 자연스럽게 배치합니다.

파일 간 링크를 PDF 내부 이동 앵커로 변환

전문 기술 문서 집합은 장과 장 사이의 유기적인 상호 참조가 매우 빈번합니다:

• 로컬 링크 감지: md2pdf는 .md 확장자를 향하는 링크를 식별하여 현재 컴파일 대기 중인 문서 목록과 비교합니다.
• 내부 목적지 앵커 연결: 대상 파일이 함께 컴파일되는 전자책의 한 챕터인 경우, 외부 링크 대신 PDF 내부 목적지 링크로 대체합니다.
• 외부 저장소 대체 링크: 함께 묶이지 않은 외부 파일에 대한 링크는 GitHub 공개 웹페이지 주소로 안전하게 유지합니다.

로컬 마크다운 파일과 이미지 번들 동시 업로드

사용자 컴퓨터에 있는 마크다운 문서를 변환할 때도 md2pdf는 이미지 동시 업로드를 지원합니다:

파일 선택 창에서 마크다운 문서와 이미지 파일들을 함께 선택하면, md2pdf가 메모리상에서 파일명과 상대 경로를 즉시 매핑합니다. 외부 서버에 이미지를 올릴 필요 없이 로컬 도표를 온전히 PDF에 반영할 수 있습니다.

이미지와 링크가 온전한 완벽한 PDF 문서 생성

상대 경로 이미지와 내부 링크가 완벽하게 복원되면 문서의 완성도가 비약적으로 향상됩니다. md2pdf를 사용하면 선명한 해상도의 다이어그램과 유기적으로 연결된 챕터 링크를 갖춘 최상급 PDF 문서를 제작할 수 있습니다.