mdBook, 쿼츠(Quartz), MkDoc, HonKit와 같은 문서 툴은 모두 마크다운을 지원하며, 다른 다양한 언어 및 형식과 호환된다. 각 툴의 돋보이는 기능과 적절한 용도를 간략히 살펴보자.
마크다운 텍스트 형식은 사람이 읽을 수 있으면서 HTML로 즉시 변환이 가능한 텍스트를 손쉽게 만들 수 있게 해준다. 원래는 블로그와 메시지 보드용으로 개발됐지만 지금은 문서를 위한 소스 형식으로 폭넓게 사용되고 있다.
ⓒ Getty Images Bank 이 기사에서는 4가지 문서 생성 툴(mdBook, 쿼츠, MkDoc, HonKit)을 살펴본다. 모두 마크다운을 주 소스로 지원한다. 또한 전자책, PDF 등 마크다운을 출판 가능한 형식으로 변환하고자 하는 다른 모든 프로젝트에서 사용할 수 있다.
마크다운 확장 지원
핵심 마크다운 구문은 HTML 또는 주석 유형의 작은 일부만 지원한다. 그 빈 틈을 채우기 위해 마크다운을 위한 확장과 애드온이 등장했다(예를 들어깃허브 버전의 마크다운). 이 기사에서 소개하는 각 툴은 기본적으로 또는 플러그인을 통해 다양한 확장을 지원한다. 수학 마크업과 같이 다소 특이한 요구사항도 적절한 마크다운 확장을 사용하면 어렵지 않게 지원할 수 있다.
mdBook
대부분의 프로젝트는 내부 툴을 사용해 문서를 생성하는데,mdbook이 전형적인 예다. 러스트로 작성됐으며 러스트 언어 프로젝트는 mdbook을 사용해러스트 프로그래밍 언어(Rust Programming Language)와 같은 문서를 생성한다. 그러나 확장을 직접 만들 계획이 아닌 한 mdbook을 사용하기 위해 러스트를 잘 알아야 할 필요는 없다. 툴을 그대로 사용하려면 사전 컴파일된 바이너리를 다운로드해서 바로 사용하면 된다.
mdBook 프로젝트의 설정 프로세스는 러스트 또는 다른 현대 프로그래밍 언어에서 새 프로젝트를 초기화하는 과정과 비슷하다. mdBook 명령줄 툴인 mdbook init을 실행해서 빈 책 프로젝트를 새로 생성한다. 여기에는 .gitignore를 포함한 최소한의 상용구가 미리 입력돼 있다. 그런 다음 인터랙티브 방식으로 또는 명령줄에서 기본적인 세부 사항을 제공할 수 있다.
mdBook 프로젝트의 중심은 목차 역할을 하는 SUMMARY.md 파일이다. 일반적인 마크다운 표기법을 사용해 책의 파일에 연결하고 부제목 아래에 배치하고 계층 구조로 정렬한다. SUMMARY.md에 아직 존재하지 않는 파일에 대한 링크를 제공하는 경우 책에서 빌드 프로세스를 실행할 때 파일이 자동으로 생성되고 H1 부제목으로 페이지 제목이 채워진다.
SUMMARY.MD의 예를 들면 다음과 같다.
# Summary
[Introduction](README.md)
---
- [Chapter 1: Installing The Nothing App](./chapter_1.md) - [Chapter 2: Using The Nothing App](./chapter_2.md) - [Use Cases](./chapter_2_1.md) - [Chapter 3: Removing The Nothing App](./chapter_3.md) - [Manually Deleting User Data](./chapter_3_1.md)
일반적으로 필요에 따라 build 명령을 사용해 책의 HTML을 재생성하지만, watch를 사용해서 로컬 웹 서버에서 인터랙티브하게 빌드되는 페이지를 제공하는 편이 더 편리한 경우가 많다. 소스 파일이 변경되면 자동으로 다시 빌드되므로 문서를 작성하면서 실시간에 가깝게 문서가 어떻게 보이는지 확인할 수 있다.
책에 코드 예제가 있는 경우 코드에 대한 테스트를 자동으로 생성할 수 있다. 현재 mdBook은 러스트 코드 블록만 이 방식으로 테스트하며, 이를 위해서는 적절한 테스트 모음을 제공해야 한다. 그러나 이 기능이 다른 프로그래밍 언어로 확장될 여지는 있다.
이 부분은 러스트 프로젝트 문서화에 초점을 맞춘다는 mdBook의 가장 큰 한계를 보여준다. 전처리기 확장 시스템을 통해 툴을 확장할 수 있지만 그러한 전처리기를 작성하려면 러스트를 알아야 한다. 사용할 수 있는 몇 가지 써드 파티 플러그인에는 다른 부분(예를 들어 LaTeX)에 대한 지원이 충분히 포함돼 있으므로 러스트 외의 프로젝트에서 문서화를 위한 용도로도 mdBook을 고려할 만하다.
쿼츠(Quartz)
이제 버전 4에 이른쿼츠는 마크다운에서 문서를 출판하는 용도뿐만 아니라 노트 모음 또는 제작자인 재키 차오가 말하는 '디지털 가든'을 공유하는 용도로도 사용 가능하다. 쿼츠는 인기 있는 마크다운 기반 노트 앱인 옵시디언(Obsidian, 쿼츠와 이름이 잘 어울린다)과 통합되며, 마크다운 형식을 지원하는 모든 텍스트 편집기를 사용할 수 있다.
쿼츠에는 독립형 바이너리 설치 프로그램이 없다. 소스에서 설치하거나(실행하려면 Node.js 필요) 도커 컨테이너를 가져와서 설정할 수 있다. 쿼츠의 이전 버전은 휴고(Hugo) 정적 사이트 생성기에 대한 종속성으로 인해 설정이 상당히 복잡했지만 버전 4는 완전히 다시 작성됐다.
기본적으로 소스 트리의 content 디렉터리는 쿼츠가 마크다운 소스 파일을 찾는 위치다. 또한 쿼츠는 program 디렉터리의 구성 파일에 의존해서 사이트 구성과 레이아웃을 설명한다. 따라서 하나의 쿼츠 소스 설치를 사용해서 구성과 레이아웃이 서로 다른 여러 사이트를 구축하기는 어렵다.
쿼츠의 문서에는 메타데이터가 저장된 프론트 매터(front matter)라는 것이 있다. 프론트 매터 메타데이터는 플러그인을 통해 맞춤 설정할 수 있지만 대부분의 프로젝트에는 기본적으로 지원되는 메타데이터로 충분하다. 문서 콘텐츠가 포함된 예를 들면 다음과 같다.
--- title: A Typing Test draft: false tags: - qwerty ---
Jackdaws *love* my big sphinx of **quartz**!
참고로 마크다운 문서에서 만든 링크에 대한 대상은 사이트를 구축할 때 자동으로 생성되지 않으므로 링크는 404 페이지로 이동한다.
쿼츠의 정말 좋은 점 중 하나는 독자를 위한 풍부하고 강력한 기본 기능이다. 백링크, 탐색 경로, 콜아웃, 팝오버 미리보기 모두 마크다운에서 자동으로 또는 프로그램을 통해 생성이 가능하다. LaTeX와 머메이드(Mermaid) 다이어그램도 기본 지원되며, 입력과 동시에 검색하기, 탐색 시 스타일이 지정되지 않은 콘텐츠가 깜박이는 것을 방지하기 위한 단일 페이지 앱 라우팅과 같은 강력한 사용자 기능이 제공된다. 또한 타입스크립트로자체 플러그인을 작성할 수도 있다.
MkDocs
파이썬으로 만들어진MkDocs는 비교적 간단한 마크다운 문서 생성기 중 하나다. 핵심 기능이 많지는 않지만 풍부한 플러그인 생태계를 통한 확장성이 뛰어나다.
MkDocs에는 독립적인 설치 프로그램이 없지만 파이썬 환경 내에서 실행되며 pip install mkdocs를 사용해 설정이 가능하다. 프로그램을 실행하고 명령을 내리기 위한 파이썬 환경용 명령줄 툴을 제공한다. mkdocs new <directory>를 입력하면 제공된 디렉터리에 간소한 새 문서 프로젝트가 생성되며 mkdocs serve는 로컬 웹 서버를 실행해 현재 디렉터리의 문서 프로젝트를 표시한다.
새 MkDocs 프로젝트는 index.md(목차)와 mkdocs.yml 구성 파일, 두 개의 파일로 시작된다. (README.md를 인덱스 파일로 사용할 수도 있음) 구성 파일은 문서 프로젝트의 메타데이터와 파일을 목차로 정리하는 방법을 제공한다. 예를 들면 다음과 같다.
nav: - Home: index.md - User Guide: - Writing your docs: writing-your-docs.md - Styling your docs: styling-your-docs.md - About: - License: license.md - Release Notes: release-notes.md
nav: 블록을 제공하지 않으면 MkDocs는 문서 디렉터리에 파일 이름을 기준으로 정렬된 모든 .md 파일을 자동으로 검색해서 자동으로 블록을 생성한다.
몇 가지 중요한 기능이 기본 제공된다. 좋은 문서의 대표적인 기능인 입력과 동시에 검색하기는lunr.js프로젝트를 통해 포함돼 있다. 사이트를 사전 인덱싱할지(규모가 큰 사이트에 좋음) 여부와 같은 조정 가능한 몇 가지 옵션이 제공된다. 지원되는 마크다운에는 테이블 및 코드 하이라이트와 같은몇 가지 확장이 기본적으로 포함된다. 문서를 위한 메타데이터는 쿼츠의 프론트 매터 형식을 따르거나멀티마크다운(MultiMarkdown) 메타데이터 스타일을 사용할 수 있다. 동일한 프로젝트에서 두 스타일을 바꿔 사용할 수 있지만 문서를 렌더링하는 데 사용 중인 테마에 따라 지원되는 메타데이터 키가 달라진다.
MkDocs의 빈약한 핵심 기능은방대한 플러그인 및 보조 프로젝트 생태계로 상당부분 상쇄된다. 테마, API로 문서 생성하기, 그래픽과 차트, 코드 상호작용과 실행(예를 들어인라인 주피터 노트북), 마크다운을 위한 추가 확장 등이 있으며 그 외에도 많은 범주의 기능이 생태계에 포함돼 있다.
HonKit
오픈소스 렌더링 프론트 엔드를 사용하는 상용 문서 호스팅 서비스로 깃북(Gitbook)이 있다.HonKit는 2018년쯤 만들어진 깃북 프로젝트의 포크이며 깃북과 많은 부분이 호환되지만 별도의 개발 팀이 있다. 또한 깃북의 오픈소스 부분이 GNU GPL 3를 사용하는 반면 HonKit는 아파치를 사용하므로 라이선스의 자유도가 높다.
HonKit의 핵심 기능은 잘 선별된 최소한으로 구성된다. Node.js 라이브러리와 명령줄 툴로 모두 작동하며 마크다운 또는 AsciiDoc 파일에서 문서를 생성한다. npm을 사용해서 HonKit를 글로벌 또는 로컬로 설치하면 npx honkit를 사용해 명령에 액세스할 수 있다. init 명령은 빈 책을 새로 설정하고 serve는 로컬로 책을 미리보고 build는 출력을 렌더링한다. 추가 플러그인 없이 PDF, ePub, Mobi 형식 출력이 모두 포함되며, 표지 그림도 자동으로 포함할 수 있다.
마크다운 파일은 쿼츠에 따라 YAML 스타일의 프론트 매터를 사용할 수 있으며 여기에 정의된 변수는 사용자가 자체 템플릿에 사용할 수 있다. HonKit는 테이블, 일반적인 구문 하이라이트가 포함된 코드 블록, 간단한 각주를 포함해 기본적이지만 유용한 마크다운 기능 집합을 지원한다.
새 HonKit 책을 만들기 위해 필요한 유일한 파일은 소개 역할을 하는 README.md다. 개략적인 스타일로 작성되는 목차(SUMMARY.md)는 선택 사항이며 책을 위한 JSON 기반 구성 데이터도 마찬가지다. 후자는 파일 경로, 출판 세부 사항, 출력을 렌더링하는 데 사용된 프로그램 버전 등 다양한 세부 정보를 포함할 수 있다.
깃북과HonKit용 플러그인은 수백 개에 이른다. HonKit는 두 가지 유형의 플러그인을 바꿔가며 사용할 수 있으므로 모든 문서화 작업, 특히 깃/깃허브 기반 통합을 사용하는 작업에서 어렵지 않게 기본 기능을 확장할 수 있다.
결론
모든 러스트 또는 러스트 관련 프로젝트에서는 mdBook이 가장 좋은 선택이다. 러스트 언어로 만들어졌고 애초에 러스트 프로젝트를 위한 문서를 생성하도록 고안됐기 때문이다.
그러나 다운로드해서 바로 사용하는 문서 생성 환경을 원하는 사람에게도 유용하다. 쿼츠는 Node.js를 사용하므로 이미 노드 앱을 만들고 있는 경우가 아니라면 약간의 추가 작업이 필요하지만 방대한 기본 기능을 탑재했다. MkDocs의 경우 종속 요소로 파이썬이 필요하며 기본적으로 매우 간소하지만 풍부한 플러그인 생태계가 있다.
또한 파이썬 사용자는 MkDocs를 라이브러리로 사용하는 것만으로 확장할 수 있다. HonKit 역시 소하지만(Node.js도 필요함) 깃북 포크인 만큼 방대한 서드파티 생태계를 갖췄다.
