한 가지 포스트로 여러 파일 형식을 만들 수 있다면? Jekyll의 숨겨진 가능성

은퇴 후 처음 만난 Jekyll의 한계

작년에 서울대학교 물리학과에서 정년퇴직한 후, 나는 지난 40년간 강의한 내용들을 정리하는 프로젝트를 시작했습니다. GitHub Pages와 Jekyll을 선택한 이유는 간단했습니다. 비용이 들지 않고, 마크다운으로 쉽게 작성할 수 있으며, 버전 관리까지 가능하다는 점이 매력적이었거든요.

그런데 몇 개월 뒤, 예상치 못한 문제가 발생했습니다. 매주 수요일마다 올리는 ‘물리학 세미나’ 포스트를 방문자들이 자신의 캘린더 애플리케이션에 추가하고 싶다는 요청이 들어온 것입니다. iCal 형식(.ics)으로 된 파일이 필요하다는 뜻이었습니다.

처음엔 간단하게 생각했습니다. “그냥 두 개의 포스트를 만들면 되지 않을까?” 하지만 같은 내용을 두 번 유지보수하는 것은 실수를 초래하기 쉬웠습니다. 검색해본 결과, Jekyll 커뮤니티에서도 오래전부터 제기된 이슈임을 알게 되었습니다.

Jekyll의 현재 제한사항과 그 배경

Jekyll은 기본적으로 한 개의 markdown 파일에서 한 가지 형식의 output을 생성하도록 설계되었습니다. 예를 들어, _posts/2026-07-30-seminar.md 파일은 HTML 페이지만 생성합니다. 이것이 대부분의 블로그에는 충분하지만, 교육용 콘텐츠나 이벤트 정보를 다루는 사이트에서는 문제가 됩니다.

내 경우, 각 세미나 포스트마다 세 가지 형식이 필요했습니다. 첫째는 상세한 설명이 포함된 HTML 페이지, 둘째는 일정 애플리케이션에 추가할 수 있는 iCal 파일, 셋째는 인쇄할 수 있는 PDF였습니다.

Jekyll의 layout 시스템만으로는 이를 구현할 수 없었습니다. 각 layout은 하나의 출력 형식만 담당하기 때문입니다. 결국 저는 세 가지 해결 방안을 시도해보기로 했습니다.

세 가지 실제 해결 방법

첫 번째 방법: 플러그인 활용하기

처음 시도한 방법은 커스텀 Jekyll 플러그인을 작성하는 것이었습니다. 플러그인을 통해 post-processing 단계에서 하나의 마크다운 파일로부터 여러 형식의 파일을 생성했습니다. Ruby를 이용해 다음과 같은 로직을 구현했습니다:

• 원본 마크다운 파일에서 front matter 정보(제목, 날짜, 위치 등)를 추출
• 동일한 데이터를 이용해 HTML 레이아웃과 iCal 레이아웃에 각각 전달
• PDF 생성 플러그인(jekyll-pdf 또는 유사한 도구)과 연동

실제로 이 방법은 작동했습니다. 다만 로컬에서 생성할 때는 문제없었지만, GitHub Pages에 배포할 때는 보안 정책 때문에 많은 플러그인이 차단된다는 문제가 있었습니다.

두 번째 방법: 빌드 스크립트 자동화하기

다음으로 시도한 방법은 GitHub Actions와 빌드 스크립트를 활용하는 것이었습니다. _data 폴더에 seminar.yml 파일을 만들어 모든 세미나 정보를 중앙에서 관리하고, Python 스크립트로 마크다운과 iCal 파일을 동시에 생성했습니다.

이 방법의 장점은 정보의 단일 소스를 유지하면서도 여러 형식의 파일을 생성할 수 있다는 점이었습니다. 매주 seminar.yml만 업데이트하면, 자동으로 HTML 페이지와 .ics 파일이 모두 생성되었습니다.

세 번째 방법: 동적 콘텐츠 생성하기

가장 깔끔한 해결책은 JavaScript를 활용한 클라이언트 측 생성이었습니다. HTML 페이지에 필요한 모든 메타데이터를 JSON 형식으로 포함시킨 후, 방문자가 페이지에서 ‘캘린더에 추가’ 버튼을 클릭하면 브라우저에서 즉시 iCal 파일을 생성하도록 했습니다.

이 방법은 추가 빌드 과정이 필요 없고, GitHub Pages의 모든 제약 조건을 우회할 수 있다는 장점이 있었습니다.

현재의 최선의 실천 방식

1년 반의 시행착오 끝에, 저는 세 가지 방법을 상황에 맞게 조합하는 것이 최적이라는 결론에 도달했습니다. 대부분의 콘텐츠는 HTML로만 필요하므로 표준 Jekyll을 사용하되, 특정 콘텐츠(세미나, 이벤트 등)에 대해서만 동적 생성 방식을 적용했습니다.

혹시 여러분도 Jekyll에서 같은 문제를 겪고 계신다면, 위의 세 가지 방법 중 어느 것이 여러분의 상황에 가장 적합한지 생각해보시고, 댓글로 여러분의 경험을 공유해주시기 바랍니다.