Jekyll로 한 페이지에서 HTML과 PDF를 동시에 생성하는 방법

은퇴 후 블로그를 시작한 노 교수의 고민

작년에 대학을 정년퇴직한 후, 나는 평생 가르쳤던 경제학 강의 노트들을 정리하여 온라인에 공유하기로 결심했습니다. GitHub Pages와 Jekyll을 활용하면 무료로 블로그를 운영할 수 있다는 조언을 받았거든요. 처음엔 HTML 형식의 포스팅만으로도 충분하다고 생각했습니다. 그러나 구독자들로부터 예상치 못한 요청이 들어오기 시작했습니다.

“교수님, 이 글을 PDF로도 받을 수 있을까요? 회의 때 인쇄해서 가져가고 싶은데요.”

“혹시 iCal 형식으로 강의 일정을 공유할 수 없을까요? 제 구글 캘린더에 자동으로 추가되면 좋겠어요.”

처음엔 각각의 요청에 대응하기 위해 별도의 파일을 수동으로 생성하고 관리했습니다. 하지만 포스팅을 수정할 때마다 여러 형식의 파일을 모두 업데이트해야 한다는 것은 정말 번거로운 일이었습니다. 마치 종이에 적은 강의 노트를 다시 필기하는 것과 같은 중복 작업이었죠.

이 문제를 해결하기 위해 나는 GitHub의 Jekyll 이슈 페이지를 뒤지기 시작했습니다. 그리고 3041번 이슈에서 내 고민과 정확히 일치하는 제안을 발견했습니다. 바로 “하나의 포스트에서 여러 출력 형식을 생성할 수 있게 해달라”는 요청이었습니다.

Jekyll의 현재 제한사항과 실제 문제

Jekyll의 기본 구조를 이해하려면 먼저 레이아웃(Layout)의 개념을 알아야 합니다. 현재 Jekyll은 한 페이지마다 기본적으로 하나의 레이아웃만 적용할 수 있습니다. 예를 들어, 블로그 포스트는 post.html 레이아웃을 사용하고, 이를 통해 HTML 형식의 파일만 생성됩니다.

내가 겪었던 문제는 이것이었습니다. 동일한 콘텐츠로부터 HTML, PDF, iCal 등 여러 형식의 파일을 한 번에 생성하고 싶었지만, Jekyll의 기본 기능으로는 불가능했던 것입니다. 각 형식마다 별도의 포스트를 만들거나, 복잡한 스크립트를 작성해야만 했습니다.

더욱 답답했던 점은 포스팅을 수정할 때마다 모든 형식의 파일을 일일이 갱신해야 한다는 것입니다. 한 번의 오타 수정이 5개의 파일 수정으로 이어지는 악순환이 반복되었습니다. 이는 데이터 일관성 문제로도 이어져, 때로는 어느 버전이 최신인지 헷갈리기까지 했습니다.

실용적인 해결책: 플러그인 활용과 빌드 자동화

결국 나는 두 가지 접근 방식을 조합하여 문제를 해결했습니다. 첫 번째는 Jekyll 플러그인을 활용하는 방법입니다.

Ruby 기반의 Jekyll 플러그인을 작성하면, 빌드 과정에서 각 포스트를 처리할 때 여러 형식의 출력 파일을 동시에 생성할 수 있습니다. 예를 들어, 포스트의 Front Matter에 formats: [html, pdf, ical]이라고 명시하면, 같은 콘텐츠로부터 세 가지 형식의 파일이 자동으로 생성되는 것입니다.

구체적으로, 내가 구현한 방식은 다음과 같습니다. 각 포스트의 Front Matter에 원하는 출력 형식을 지정하고, 커스텀 플러그인이 Jekyll의 post_write 훅을 실행할 때 이를 감지합니다. 그 다음 Pandoc이나 다른 변환 도구를 호출하여 HTML을 PDF나 다른 형식으로 자동 변환하게 하는 것입니다.

두 번째는 GitHub Actions를 활용한 빌드 자동화입니다. Jekyll 빌드가 완료된 후, 추가 스크립트를 실행하여 필요한 형식의 파일들을 생성하고 배포하는 방식입니다. 이는 로컬 환경에 복잡한 의존성을 설치할 필요 없이, 클라우드 환경에서 모든 변환 작업을 처리할 수 있다는 장점이 있습니다.

실제로 적용해본 결과, 이제 내가 해야 할 일은 포스트를 작성하고 Front Matter에 원하는 출력 형식만 명시하는 것뿐입니다. 나머지는 모두 자동화됩니다. 포스팅을 수정할 때도 원본 마크다운 파일 하나만 수정하면, 모든 형식의 파일이 자동으로 업데이트됩니다.

커뮤니티와 함께 만드는 미래

흥미롭게도, 내가 겪었던 이 문제는 전 세계의 Jekyll 사용자들이 모두 공감하고 있었습니다. GitHub의 3041번 이슈는 많은 댓글과 함께 수년간 논의되어 왔습니다. 일부 개발자들은 이미 이 기능을 구현하는 플러그인들을 공개했고, 커뮤니티 차원에서 해결책들을 공유하고 있었습니다.

내 경험을 바탕으로 말씀드리자면, Jekyll은 단순함이 장점이지만, 이런 실제 요구사항들을 충족시키기 위해서는 개발자의 창의력과 커뮤니티의 협력이 필수입니다. 나 역시 이제 내가 구현한 솔루션을 오픈소스로 공개할 준비를 하고 있습니다.

만약 당신도 Jekyll로 운영하는 블로그에서 여러 형식의 파일을 동시에 생성해야 한다면, 먼저 GitHub의 Jekyll 이슈 페이지를 방문해 보세요. 당신과 같은 고민을 하는 사람들의 해결책들을 찾을 수 있을 것입니다. 그리고 혹시 더 나은 방법을 발견하신다면, 커뮤니티와 함께 그 경험을 나누어주시길 바랍니다.