Pandoc 이미지 관련 팁 두 가지
류광Pandoc으로 마크다운을 epub로 변환할 때 유용한 팁들을 공유하고자 합니다. 오늘은 이미지 관련 팁 두 가지입니다.
범용 문서 변환 도구 Pandoc을 사용하면서 배운 것들을 종종 공유하고자 합니다. 주로는 마크다운->epub 변환과 관련한 사항들인데요. 오늘은 이미지 관련 팁 두 가지입니다.
스타일시트에서 참조하는 이미지 파일의 누락 문제
마크다운 문서나 HTML 문서를 epub로 변환할 때 Pandoc은 문서가 참조하는 미디어 파일을 자동으로 epub에 포함시킵니다. 예를 들어 다음과 같은 줄이 있는 마크다운 문서를 epub로 변환하면,
Pandoc은 some-image.png를 찾아서 epub 파일에 넣습니다. 그런데 이것은 주된 입력 문서에만 해당하고, epub 파일에 쓰이는 스타일시트에는 해당하지 않습니다. 예를 들어 Pandoc 실행 시 --css 옵션으로 지정한 스타일시트에 다음과 같은 규칙이 있어도, Pandoc이 another-image.png를 자동으로 epub 파일에 넣어 주지는 않습니다.
.fancy-block {
background-image: url("../media/another-image.png");
}마크다운 문서의 어딘가에 인위적으로  같은 문구를 두면 Pandoc이 epub 파일에 넣을 것이므로 문제가 해결이 될 것 같지만, 안타깝게도 그렇지는 않습니다. 이미지 파일을 epub 파일에 포함하는 과정에서 Pandoc이 이미지 파일의 이름을 일정한 규칙에 따라 변경하기 때문입니다. 변환 과정에서 another-image.png가 file01.png 같은 이름으로 바뀌므로 .fancy-block에 대한 CSS 규칙은 존재하지 않는 이미지 파일을 참조하게 됩니다.
한 가지 해결책은 epub 파일을 생성한 후 epub 파일 안의 이미지 파일들을 조사해서 another-image.png에 해당하는 파일 이름을 알아낸 후 CSS 스타일시트를 변경하는 것인데, 너무 번거롭지요.
현재 제가 아는 제일 쉬운 방법은[1] --epub-embed-font 옵션을 이용(남용?)하는 것입니다. Pandoc 실행 시 --epub-embed-font=another-image.png라는 옵션을 추가하면 another-image.png가 epub 파일의 EPUB/fonts/ 디렉터리에 이름 변경 없이 저장되므로, CSS 스타일시트에서는 background-image: url("../fonts/another-image.png") 형태로 참조하면 됩니다.
이미지 파일이 fonts 디렉터리에 들어가는 게 좀 불만이지만, Pandoc이 스타일시트를 좀 더 지능적으로 처리하도록 개선되기 전에는 이 방법이 최선인 것 같습니다.
원치 않는 이미지 캡션
접근성(accessibility)을 위해, EPUB 표준은 모든 이미지에 이미지 설명을 alt 특성으로 지정할 것을 요구합니다.
마크다운에서 이미지는  형태로 표기하는데, HTML 변환 시 대괄호 쌍 안의 문구(지금 예에서 그림 설명)이 img 태그의 alt 특성의 값이 됩니다.
처럼 설명을 생략해도 Pandoc이 불평하지 않지만, 그런 식으로 만든 epub 파일은 epubcheck를 통과하지 못합니다. 따라서 반드시 대괄호 쌍 안에 그림 설명 문구를 넣어야 합니다. 그리고 꼭 EPUB 표준 준수가 아니더라도, 문서 작성 시 접근성을 고려하는 것은 중요한 일입니다.
그런데  같은 요소가 하나의 줄을 온전히 차지하는 경우 Pandoc은 그것을 하나의 '그림(figure)' 블록으로 간주해서 캡션을 추가합니다. 예를 들어 Pandoc은 다음과 같은 마크다운을
다음과 같은 HTML로 변환합니다.
<figure>
<img src="some-figure.png" alt="그림 설명" />
<figcaption aria-hidden="true">그림 설명</figcaption>
</figure>그림 캡션을 따로 작성하는 경우에는 Pandoc의 이런 처리가 불편한데요. 그렇다고 그림 설명 부분을 생략하면 접근성을 해치게 됩니다. 한 가지 해결책은 Pandoc향 마크다운의 확장 문법인 {특성=값} 구문을 활용하는 것입니다. 예를 들어 Pandoc은 다음을
{alt="그림 설명"}다음과 같이 평범한 img 요소로 변환합니다.
<p><img src="some-figure.png" alt="그림 설명" /></p>대괄호 쌍이 비어서 캡션이 생기지 않았고, 그러면서도 img 요소의 alt 특성은 지정되었습니다.