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