지식 출판 도구 3종 비교
- 코드 실행 결과가 포함된 책을 만들 때는 Quarto를 사용하세요. 수식 표현력이 가장 깊습니다.
- 가볍고 가독성 좋은 일반 텍스트 위주 책은 MkDocs를 사용하세요. Lubuntu에서 가장 쾌적하며 학생들이 따라 하기 가장 쉽습니다.
- Obsidian의 Bases 기능이나 연결망을 그대로 웹에 보여주고 싶을 때는 Quartz를 사용하세요.
| 비교 항목 | Quarto | MkDocs | Quartz |
| 핵심 철학 | 과학적 집필 및 프로그래밍 (Code) | 기술 문서 및 매뉴얼 (Docs) | 개인 지식 베이스 공유 (Garden) |
| 기반 언어 | C++ (Pandoc 기반) | Python | TypeScript (Node.js) |
| 주요 강점 | 코드 실행 결과 포함, 수식 완벽 | 가볍고 빠름, 유려한 UI (Material) | Obsidian 문법 완벽 호환, 그래프 뷰 |
| 추천 용도 | 데이터 과학 책, 논문, | 사용자 가이드, 매뉴얼 | 위키, 개인 메모 웹 게시, 기술 블로그 |
| 설치 방식 | 전역(Global) 설치 | 가상 환경(Local venv) 설치 권장 | 프로젝트별(Local npx) 설치 권장 |
도구별 '굽는 과정' 가이드
보관소 경로(~/Documents/MyBook)를 기준으로 각 도구가 어떻게 원고를 처리하는지 설명합니다.
① Quarto: "직접 변환 방식"
Quarto는 엔진이 외부(전역)에 있고, 원고가 있는 곳에서 바로 명령을 내려 결과물을 뽑아냅니다.
- 원고 위치:
~/Documents/MyBook - 설정 파일:
_quarto.yml(원고 폴더 루트에 위치) - 연결 및 굽기: 1. 터미널에서
cd ~/Documents/MyBook실행. - 검증:
quarto preview명령어를 입력하면 로컬 서버가 뜨며 실시간 수정 사항이 반영됩니다.
② MkDocs: "내부 수렴 방식"
MkDocs는 보통 원고 폴더를 프로젝트 폴더로 삼고, 그 안에 가상 환경을 구축하여 굽습니다.
- 원고 위치:
~/Documents/MyBook/docs(MkDocs는 관례상docs폴더 안을 봅니다) - 설정 파일:
~/Documents/MyBook/mkdocs.yml - 연결 및 굽기:
- 검증:
mkdocs serve명령어를 입력하면 $http://127.0.0.1:8000$에서 에러 체크 가능. (링크 오류 시 터미널에 즉시 경고)
③ Quartz: "외부 연결(Symlink) 방식"
엔진 폴더를 따로 만들고 원고를 그 안으로 '링크' 거는 방식입니다.
- 원고 위치:
~/Documents/MyBook - Quartz 엔진 폴더:
~/Documents/MyBook-Web(별도 생성) - 연결:
- 검증:
npx quartz build --serve실행 후 $http://localhost:8080$에서 확인.
세 도구 모두 GitHub Actions로 가기 전, 로컬 서버(preview, serve, --serve)를 띄워놓고 수식을 수정했을 때 렌더링이 깨지는지를 가장 먼저 확인하는 것이 좋습니다.