Summary
- Quartz는 옵시디언의 마크다운 파일을 HTML/CSS/JS로 변환하는 정적 사이트 생성기(SSG)이며, 변환 결과물은
public폴더에 모인다.- GitHub에 push하면 Cloudflare가 직접 빌드하는 일반적인 방식은, 파일을 블로그 전용 폴더로 일일이 복사해야 해서 “단일 Vault 통합 관리”라는 목표와 어긋난다.
- 복사를 없애려고 심볼릭 링크를 쓰면, Cloudflare가 로컬 경로를 따라갈 수 없어 빌드 에러가 난다.
- 해결책은 로컬 빌드 전략이다. 로컬에서
npx quartz build로 빌드하고, 완성된public폴더만 강제로 push한다.- Cloudflare는 빌드 없이
public을 그대로 서빙하므로, 단일 Vault 유지·배포 안정성·서빙 속도를 모두 얻는다.
실습 환경
이 시리즈는 macOS 기준으로 작성했다. 경로 표기(
/Users/...), 셸 명령(ln -s,lsof), 단축키가 Windows와 다르므로 각자 환경에 맞게 바꿔 읽어야 한다.
들어가며
옵시디언(Obsidian)으로 지식을 관리하다 보면 블로그용 파일과 개인 메모를 하나의 Vault에서 통합 관리하고 싶어진다. 문제는 일반적인 블로그 배포 방식이 이 목표와 정면으로 충돌한다는 점이다.
이 글은 왜 남들과 다른 배포 구조를 짜야 했는지, 그 원리를 다룬다. 실제 설정 작업은 다음 글에서 진행한다.
Quartz와 정적 사이트 생성(SSG)
Quartz는 마크다운 파일을 웹사이트로 변환해주는 정적 사이트 생성기(SSG, Static Site Generator)다.
우리가 글을 쓰는 옵시디언의 파일 형식은 .md(마크다운)이다. 하지만 웹 브라우저가 이해할 수 있는 언어는 HTML, CSS, JS 뿐이다. 이 간극을 메우는 것이 Quartz의 역할이다.
- 원시 데이터: 옵시디언의
글.md,이미지.png - Quartz의 역할: 이것들을 엮고 디자인을 입혀
index.html같은 웹 문서로 변환한다. 이 과정을 **Build(빌드)**라고 한다. - 결과물: 변환이 완료된 파일이 모이는 곳이
public폴더다.
기존 배포 방식의 한계
일반적인 자동 빌드 방식
보통 GitHub와 Cloudflare로 블로그를 만들 때는 다음 순서를 따른다.
- 로컬의 마크다운 파일을 GitHub에 업로드(
push)한다. - GitHub에 새 파일이 올라오면 Cloudflare 서버가 이를 감지한다.
- Cloudflare 서버가 직접 Quartz를 실행해 웹 문서로 변환(Build)한다.
- 완성된 사이트를 배포한다.
자동화 자체는 괜찮지만, “하나의 옵시디언 Vault에서 통합 관리” 라는 방향과는 맞지 않는다. 이 방식을 쓰려면 블로그 배포 전용 폴더로 파일을 일일이 복사해 옮겨야 하기 때문이다.
심볼릭 링크를 쓰면 생기는 문제
복사의 귀찮음은 심볼릭 링크(Symbolic Link) 로 해결할 수 있다. 심볼릭 링크는 진짜 파일이 아니라 **“진짜 파일은 로컬의 <Vault 내 블로그 전용 폴더>에 있다”고 알려주는 주소표(이정표)**다. 이 주소표 덕분에 파일을 복사하지 않아도 옵시디언에서 글을 쓰는 즉시 블로그 폴더에 반영된다. (자세한 세팅법은 2부 Vault 심볼릭 링크 연결하기에서 다룬다.)
문제는 이 주소표를 GitHub에 올리는 순간 발생한다.
심볼릭 링크와 원격 빌드는 함께 쓸 수 없다
Cloudflare 서버는 빌드를 위해 주소표를 열어본다. 이때 주소표가 가리키는 곳은 내 로컬 경로인
<Vault 내 블로그 전용 폴더>다.
Cloudflare는 이 경로를 따라갈 수 없으므로 **빌드 에러(Build Error)**가 발생하고 사이트 배포는 실패한다.
맞춤형 배포 패러다임
워크플로우
Cloudflare가 내 로컬 경로에 접근할 수 없다면, 로컬에서 빌드하고 완성된 파일만 push하면 된다. 이것이 로컬 빌드(Local Build) 전략이다.
- 로컬 빌드: 로컬에서
npx quartz build를 실행한다. 로컬은 심볼릭 링크 주소표를 읽고 옵시디언 폴더로 들어가.md파일을 웹사이트 형태로 변환한다(결과물:public폴더). - 강제 업로드:
.gitignore를 무시하고public폴더를 GitHub에 강제로 push한다(git add -f public). 원래public은 GitHub에 올리지 않는 것이 원칙이지만, 이 전략에서는 완성된 웹사이트 파일(.html)이야말로 올려야 할 대상이다. - Cloudflare의 역할 축소: Cloudflare에서 빌드 명령어를 제거한다. Cloudflare는 GitHub에 올라온 완성형
public폴더를 그대로 배포하기만 한다.
장점
| 항목 | 내용 |
|---|---|
| 단일 Vault 유지 | 심볼릭 링크 덕분에 블로그용/개인용 폴더를 분할 관리할 필요가 없다 |
| 배포 안정성 | Cloudflare 서버 상태나 Node.js 버전 문제로 인한 빌드 에러가 없다. 로컬에서 빌드가 됐다면 사이트도 정상 배포된다 |
| 초고속 서빙 | Cloudflare는 추가 빌드 없이 public 파일만 서빙하므로 속도가 빠르다 |
마치며
이 글에서는 왜 이런 배포 구조가 필요했는지 원리를 다뤘다. 핵심은 빌드의 주체를 원격 서버에서 로컬로 옮긴 것이며, 이를 가능하게 하는 것이 심볼릭 링크다. 다음 글에서는 이 구조의 심장인 심볼릭 링크를 실제로 로컬에 설정한다.
Reference
- 다음 글 2부 Vault 심볼릭 링크 연결하기
- 전체 목차 Obsidian과 Quartz로 블로그 만들기