마크다운 작성 그리고 배포 Jekyll, Docusaurus, Quartz 비교
정리하려는 대상이 많을수록 헷갈리는 지점은 비슷하다.
“Markdown이랑 Jekyll/Docusaurus/Quartz는 무슨 관계지? 다 비슷해 보이는데 뭐가 다르지?”
핵심은 간단하다.
- Markdown = 원고(콘텐츠 포맷)
- Jekyll / Docusaurus / Quartz = 그 원고를 웹사이트로 출판해주는 도구(정적 사이트 생성기, SSG)
1) 먼저 큰 그림: Markdown은 ‘콘텐츠’, SSG는 ‘변환기’
Markdown은 글을 쓰기 좋은 포맷이지만, 그 자체로 웹사이트가 되지는 않는다.
웹으로 보여주려면 결국 HTML/CSS/JS 같은 “정적 파일”로 바뀌어야 한다.
SSG(Static Site Generator) 는 이 변환을 맡는다.
즉, “Markdown 같은 평문 → 정적 사이트” 파이프라인을 만드는 도구다. (Jekyll/Docusaurus/Quartz 모두 여기 속한다.)
2) 한 장으로 보는 관계 표
| 구분 | Markdown | Jekyll | Docusaurus | Quartz |
|---|---|---|---|---|
| 역할 | 콘텐츠 포맷(원고) | SSG(출판기) | 문서 사이트 중심 SSG | 노트/디지털 가든 중심 SSG |
| 핵심 한 줄 | 쓰기 쉬운 텍스트 원고 | “Markdown/Liquid 넣으면 정적 사이트가 나온다” | “React 기반으로 문서 사이트를 빠르게 만든다” | “Markdown을 링크-친화적인 노트 사이트로 만든다” |
| Markdown과의 관계 | 기준(입력) | Markdown(+Liquid 등) → 정적 파일 출력 | Markdown/MDX → 문서 사이트 출력 | Markdown → 개인 노트/디지털가든 사이트 출력 |
| 확장 방식 | 포맷만 제공 | 템플릿 중심(특히 Liquid) | MDX(= Markdown + JSX) 로 컴포넌트 삽입 | 백링크/그래프/위키링크 등 노트 UX 기능 내장 |
| 강한 용도 | 글/문서 원고 통일 | 블로그/일반 정적 사이트 | 제품/팀 문서 포털 | Obsidian 스타일 지식베이스 공개 |
3) Jekyll: “블로그/정적 사이트”에 강한, 오래 사랑받는 출판기
Jekyll은 공식 소개부터 “simple, blog-aware, static sites”를 강조한다.
입력은 Markdown(및 Liquid 템플릿 등)이고, 출력은 배포 가능한 정적 사이트다.
이럴 때 잘 맞는다
- 개인/팀 블로그처럼 “글 중심” 사이트
- 가볍고 단순한 정적 사이트(프로젝트 소개/랜딩 등)
- 템플릿 기반(레이아웃/테마)으로 구조를 잡는 방식이 편할 때
4) Docusaurus: “문서 운영”을 빠르게 시작하고, React로 확장하는 출판기
Docusaurus는 React 기반의 사이트 생성기이고, 문서 사이트 구축에 초점을 둔다.
특히 문서에서 자주 필요한 “구조화된 내비게이션/문서 경험”을 기본으로 제공하는 철학이 강하다.
Docusaurus를 이해하는 키워드: MDX
MDX는 “Markdown 안에서 JSX를 사용할 수 있게 해주는 포맷”이다.
즉 문서 페이지 안에 React 컴포넌트를 끼워 넣어 경고 박스, 탭, 커스텀 UI 같은 것을 자연스럽게 만들 수 있다.
이럴 때 잘 맞는다
- 제품/SDK/플랫폼 문서를 “사이트 형태로 운영”해야 할 때
- 문서 안에서 컴포넌트(React)를 써서 UX를 확장하고 싶을 때
5) Quartz: “연결된 노트”를 그대로 웹으로—디지털 가든 특화 출판기
Quartz는 Markdown 콘텐츠를 완전한 웹사이트로 변환하는 batteries-included SSG로 소개된다.
특히 Backlinks, Graph View, Wikilinks 같은 “노트 연결 경험”을 전면에 내세운다.
그래서 Obsidian vault를 웹으로 퍼블리싱하려는 흐름과도 자연스럽게 맞물린다.
이럴 때 잘 맞는다
- 개인 지식베이스/디지털 가든을 공개하고 싶을 때
- “문서”보다 “노트들의 연결 구조(링크/백링크/그래프)”가 핵심일 때
6) 결론: “목적”으로 고르면 거의 안 틀린다
- 블로그/일반 사이트 중심이면 → Jekyll
- 팀/제품 문서 운영(React/MDX 확장 포함)이면 → Docusaurus
- 노트 공개/디지털 가든(백링크/그래프/위키링크 경험)이면 → Quartz