Summary
- 하나의 옵시디언 Vault에서 개인 메모와 블로그 글을 함께 관리하면서, 파일 복사 없이 발행하는 구조를 만든다.
- 핵심 결정은 두 가지다. 심볼릭 링크로 Vault를 Quartz 프로젝트에 연결하고, 빌드를 원격이 아닌 로컬에서 수행한다.
- 시리즈는 8편으로 구성된다. 앞 4편이 구축, 뒤 4편이 운영이다.
- 각 편은 독립적으로 읽을 수 있으며, 이 문서는 전체 지도 역할만 한다.
실습 환경
이 시리즈는 macOS 기준으로 작성했다. 경로 표기(
/Users/...)와 셸 명령이 Windows와 다르므로 각자 환경에 맞게 바꿔 읽어야 한다.
시작 전 준비
이 시리즈는 심볼릭 링크로 로컬에서는 하나의 Vault를 유지하고, Cloudflare로 개인 도메인에 서빙하는 구조를 만든다. 복사도 외부 이미지 호스팅도 없이, 옵시디언에서 글을 쓰고 단축키 하나를 누르면 배포가 끝나는 환경이 목표다.
전체 아키텍처
구조를 떠받치는 결정은 두 가지뿐이다.
왜 심볼릭 링크인가. 파일 복사를 없애기 위해서다. Quartz 프로젝트의 content 폴더가 실제로는 옵시디언 Vault를 가리키도록 연결하면, 옵시디언에서 글을 쓰는 즉시 블로그 폴더에 반영된다.
왜 로컬 빌드인가. 심볼릭 링크는 로컬에서만 통하는 통로다. Cloudflare 서버는 링크 너머의 내 로컬 경로를 따라갈 수 없으므로, 원격 빌드를 시키면 반드시 실패한다. 그래서 빌드를 로컬에서 수행하고 완성된 public 폴더만 올린다. Cloudflare는 빌드 없이 그 결과물을 서빙하기만 한다.
시리즈 구성
앞 4편이 블로그를 구축하는 과정이고, 뒤 4편은 운영 예정인 이야기다.
| 순서 | 다루는 질문 | 결과물 |
|---|---|---|
| 1부 로컬 빌드와 배포 패러다임 | 왜 남들과 다른 배포 구조가 필요한가 | 로컬 빌드 전략의 이해 |
| 2부 Vault 심볼릭 링크 연결하기 | Vault와 프로젝트를 어떻게 연결하는가 | content 심볼릭 링크, Git 연동 |
| 3부 Cloudflare Pages 빌드 설정과 도메인 통합 | Cloudflare가 결과물을 그대로 받게 하려면 | 빌드 명령 비우기, 도메인 통합 |
| 4부 원클릭 배포 스크립트 구축 | 어떻게 단축키 하나로 배포하는가 | 셸 스크립트 3종, Shell Commands 연동 |
| (예정) UI 커스터마이징 1 설정과 스타일 | 색·폰트·기능을 설정으로 바꾸고 본문 스타일을 손보려면 | theme·enabled·custom.scss |
| (예정) UI 커스터마이징 2 커스텀 플러그인 저작 | Quartz에 없는 기능을 어떻게 만드는가 | 로컬 플러그인 규약 |
| (예정) 이미지 관리와 삽입 | 이미지는 어떤 경로로 배포되는가 | attachments 운영 규칙 |
| (예정) 이 블로그의 커스텀 기능 9종 | 실제로 만든 컴포넌트·트랜스포머 | 플러그인 9종 카탈로그 |
Quartz v4에서 넘어왔다면
이 시리즈는 v5 기준이다. v4로 이미 운영 중인 블로그를 이관하는 과정은 Quartz 블로그 v4에서 v5로 이관하기를 따로 참고한다.
구축
1부 로컬 빌드와 배포 패러다임에서는 정적 사이트 생성기와 로컬 빌드 전략의 필요성을 설명한다.
2부 Vault 심볼릭 링크 연결하기에서는 ln -s로 content를 연결하고 Git 캐시를 정리한다.
3부 Cloudflare Pages 빌드 설정과 도메인 통합에서는 Cloudflare의 빌드 명령을 비우고 도메인을 통합한다.
4부 원클릭 배포 스크립트 구축에서는 배포 로직을 셸 스크립트 3종으로 분리해 Obsidian 단축키에 연결한다.
구축 완료 확인
| 확인 항목 | 완료 상태 |
|---|---|
| Vault 연결 | Quartz의 content가 Vault를 가리키는 심볼릭 링크다 |
| 로컬 빌드 | public 폴더가 생성된다 |
| 로컬 미리보기 | localhost:8080에서 사이트를 확인할 수 있다 |
| 원클릭 배포 | Preview·Quick Publish·Clean Publish가 Obsidian에서 실행된다 |
| Cloudflare Pages | 빌드 명령은 비워 두고 출력 디렉터리는 public이다 |
| 실제 배포 | 연결한 도메인에서 사이트가 열린다 |
운영
이미지 관리와 삽입에서는 이미지가 사이트까지 도달하는 경로를 밝힌다. 이미지를 content/attachments/에 두면 Quartz의 Plugin.Assets()가 알아서 배포하므로, 이미지 전용 심볼릭 링크는 필요 없다.
UI 커스터마이징 1 설정과 스타일에서는 색·폰트를 설정으로 바꾸고 본문 스타일을 손본다. UI 커스터마이징 2 커스텀 플러그인 저작에서는 Quartz에 없는 기능을 로컬 플러그인으로 만드는 규약을 세운다. 이 블로그의 커스텀 기능 9종에서는 실제로 만든 컴포넌트와 트랜스포머를 정리한다.
이 구조의 특징
| 항목 | 내용 |
|---|---|
| 단일 Vault 유지 | 블로그용 폴더를 따로 두고 복사할 필요가 없다 |
| 초고속 서빙 | Cloudflare는 빌드 없이 완성된 파일만 서빙한다 |
| 대가 | 빌드가 로컬 환경에 묶인다. 스크립트와 심볼릭 링크를 설정한 기기에서만 발행할 수 있다 |
| 배포 안정성 | 로컬에서 빌드가 되면 사이트도 정상 배포된다. Cloudflare 서버 상태나 Node 버전에 좌우되지 않는다 |
마지막 항목은 이 구조를 택할 때 감수해야 할 지점이다. 원격 빌드를 포기한 대가로 안정성과 속도를 얻는 셈이다.
읽는 순서
목적에 따라 진입점이 다르다. 순서대로 읽지 않아도 된다.
- 이미 Quartz를 쓰고 있다면: 2부 Vault 심볼릭 링크 연결하기와 3부 Cloudflare Pages 빌드 설정과 도메인 통합부터 본다.
- 이미지 배포만 문제라면: 이미지 관리와 삽입 문서가 공개된 뒤 참고한다.
- 처음부터 만든다면: 1부 로컬 빌드와 배포 패러다임부터 순서대로 읽는다.
Reference
- 첫 글 1부 로컬 빌드와 배포 패러다임
- v4에서 v5로 이관: Quartz 블로그 v4에서 v5로 이관하기
- Obsidian Documentation: https://help.obsidian.md