Pandoc으로 구축한 문서 사이트, 기술적 선택과 실용성을 모두 잡다!

저자는 문서 사이트 구축을 위해 Mintlify, Docusaurus, MkDocs 등 다양한 도구를 평가했다. 특히, 자바스크립트(JavaScript) 미사용을 핵심 요구사항으로 설정하고, 단순성, 검색 기능, 스타일 적용의 용이성을 고려했다. Mintlify는 AI 기반의 기능에 집중하는 경향을 보였고, Docusaurus는 SPA(Single Page Application) 방식의 과도한 복잡성을 야기했다. MkDocs와 MdBook은 TOC(Table of Contents) 관리가 번거로웠다. 이러한 평가를 바탕으로, 유연성과 커스터마이징(Customizing)이 용이한 Pandoc을 최종 선택했다.

저자는 자바스크립트(JavaScript) 미사용을 위해 `<details>` 및 `<summary>` 태그, Popover API를 활용하여 모바일 환경에서 사이드바(Sidebar)를 구현했다. `<details>` 및 `<summary>` 태그는 간단한 구현 방식이지만, 사이드바 외부 클릭 시 닫히지 않는 단점이 있다. Popover API는 사이드바를 구현하기에 적합하지만, 검색 기능과의 연동에 제약이 있다. 이러한 기술적 선택은 사용자 경험(User Experience)과 구현 복잡도(Implementation Complexity) 사이의 트레이드오프(Trade-offs)를 보여준다.

저자는 Docusaurus의 내장 검색 기능보다 Ctrl+F를 선호하며, 자체 문서 사이트에도 Google 검색을 연동했다. 구체적으로, Google 검색을 위한 HTML form을 사용하여 검색 쿼리를 Google로 전달한다. 또한, 모든 내용을 단일 페이지로 렌더링하여 브라우저 내 검색 기능을 활용할 수 있도록 했다. 이는 검색 기능의 단순화와 사용자 친화적인 인터페이스(User-Friendly Interface)를 위한 전략으로 볼 수 있다.

저자는 Nix와 Colmena를 사용하여 문서 사이트를 빌드하고 배포하는 과정을 자동화했다. Nix를 통해 재현 가능한 빌드 환경(Reproducible Build Environment)을 구축하고, `runCommandLocal` 헬퍼를 사용하여 Pandoc 명령을 실행한다. Colmena를 사용하여 NixOS 머신에 변경 사항을 적용함으로써, 지속적인 통합(Continuous Integration) 및 지속적인 배포(Continuous Deployment) 파이프라인을 구축했다. 이러한 자동화된 배포 방식은 개발 생산성(Development Productivity)을 향상시키고, 배포 오류(Deployment Errors)를 줄이는 데 기여한다.