Tags

Blog2Callout1Cheatsheet1Cloudflare1Guide2LaTeX1Markdown1Mermaid1Obsidian2Project1Quartz3

BeautyKim Blog

Obsidian과 Quartz로 블로그 구축하기

6 min read

“기록은 옵시디언에 하는데, 블로그는 왜 따로 써야 하지?”

평소 모든 기록을 옵시디언(Obsidian)으로 하는 편이다. 하지만 이걸 남들에게 공유하려고 하니 별도의 플랫폼(Velog, 티스토리 등)에 복사·붙여넣기 하고 서식을 다시 맞추는 과정이 극도로 번거로웠다. “기록이 곧 포스팅이 되는 환경” 을 고민하다 Quartz를 이용한 블로그를 구축했다.

1. Quartz를 선택한 이유

이미 수많은 옵시디언 유저들이 Quartz를 통해 블로그를 구축하고 있어 참고할 수 있는 레퍼런스가 풍부했다. 다양한 SSG(Static Site Generator) 선택지가 존재하지만, 옵시디언과의 호환성과 커뮤니티의 규모를 고려했을 때 Quartz는 고민의 여지가 없는 독보적인 선택지였다.

  • Native 연결성: 위키링크([[]]), 백링크, 로컬 그래프 뷰를 웹에서 그대로 재현한다.
  • 개발자 친화적: TypeScript 기반이며, quartz.config.ts와 quartz.layout.ts를 통해 구조를 모듈식으로 제어할 수 있다.

2. GitHub Pages의 한계와 Cloudflare로의 전환

초기에는 가장 익숙한 GitHub Pages로 시작했다. 하지만 치명적인 문제가 있었다.

  1. Public 레포 강제: 무료 플랜에서 Pages를 쓰려면 저장소를 공개해야 한다. 내 개인적인 생각이나 미완성 메모 원본이 날것 그대로 노출되는 것은 부담스러웠다.
  2. 배포 속도: GitHub Actions는 가끔 빌드 대기 시간이 길어 흐름이 끊긴다.

해결책: Cloudflare Pages

  • Private 레포 지원: 저장소는 비공개로 유지하면서 빌드된 결과물만 웹에 노출할 수 있다.
  • CI/CD 자동화: git push만 하면 Cloudflare가 알아서 빌드한다.
  • Edge 배포: 전 세계 어디서든 빠른 속도로 블로그에 접속할 수 있다.

3. 인프라 구축 과정 (삽질 기록)

3-1. 초기 라우팅 이슈 (GitHub Actions)

초기에는 beautykim.github.io/blog 형태의 하위 경로를 사용했다. 이때 .github/workflows/deploy.yml을 설정하며 빌드 자동화를 구축했지만, 앞서 언급한 보안 이슈로 인해 과감히 인프라를 이전했다.

3-2. 기존 주소 보존: GitHub Pages 리다이렉트 전략

인프라를 Cloudflare로 옮기면서 가장 고민했던 지점은 기존 주소(beautykim.github.io/blog)의 하이퍼링크 유실이었다. 이미 공유된 링크들이 깨지는 것을 막기 위해 ‘리다이렉트 전용 레포’를 별도로 운영하기로 했다.

  • 저장소 분리: Quartz 소스 코드가 담긴 저장소는 blog-source로 이름을 바꾸고 Private으로 전환하여 보안을 강화했다.
  • 리다이렉트 레포 생성: 기존 주소를 점유하기 위해 blog라는 이름의 Public 저장소를 새로 생성했다.
  • 핵심 로직 (index.html): 이 저장소의 루트에 meta refresh와 JavaScript를 이용한 자동 이동 코드를 심었다.

HTML

<meta http-equiv="refresh" content="0; url=https://blog.beautykim.workers.dev/">
<script>window.location.href = "https://blog.beautykim.workers.dev/";</script>
  • 결과: 이제 beautykim.github.io/blog로 접속하면, GitHub Pages가 이를 읽어 즉시 Cloudflare 주소로 사용자를 토스한다. 보안(Private)과 연결성(Redirect)을 모두 잡은 설계다.

4. 디자인 커스텀: 옵시디언 감성 이식하기

가장 공들인 부분이다. 웹에서도 내가 매일 쓰는 옵시디언 앱의 느낌을 주고 싶었다.

4-1. 3단 레이아웃 이식

기본 Quartz 레이아웃을 수정해 좌측에는 탐색기(Explorer), 중앙에는 본문(Content), 우측에는 그래프 뷰와 목차(TOC)를 배치했다. 정보량이 많아도 한눈에 들어오는 구조다.

4-2. 사이드바 토글 및 애니메이션

몰입이 필요한 순간을 위해 사이드바를 접고 펼 수 있는 기능을 추가했다. 단순히 사라지는 게 아니라 부드럽게 슬라이드되는 애니메이션을 적용해 앱 사용성을 재현했다.

5. 최종 시스템 구조

  1. Obsidian: 로컬에서 글 작성 및 지식 연결.
  2. GitHub (blog-source / Private): Quartz 소스 코드 및 마크다운 원본 보관. 오직 나만 접근 가능.
  3. Cloudflare Pages: blog-source와 연결되어 push 시 자동 빌드 및 실시간 배포.
  4. GitHub (blog / Public): 리다이렉트 전용 프록시. 기존 주소 유입 시 Cloudflare로 경로 안내.

Graph View