Obsidian, Quartz, Astro로 개인 위키와 블로그를 다시 만들기

2006년 처음 블로그를 만든 이후 여러 단계를 거쳤다. 한동안은 글을 거의 쓰지 않았다. 그러다 최근 일을 쉬게 되면서 오랜만에 다시 글을 써보고 싶어졌다. 이번에는 단순한 블로그가 아니라 개인 위키와 블로그를 함께 운영하는 구조를 만들기로 했다.

1. 마크다운 기반 글쓰기 환경

1.1 기존 글쓰기 방식

그동안 글을 쓸 때는 워드나 Google Docs 같은 문서 편집기를 사용했다. 하지만 개인 위키와 블로그를 함께 운영하려면 마크다운 기반 환경이 훨씬 편리하다. 그래서 처음에는 Logseq를 사용하기로 했다.

1.2 Logseq와 Git 동기화

Logseq 그래프를 여러 기기에서 사용하기 위해 GitHub에 리포지토리를 하나 만들었다.

하지만 Logseq에는 자동 push 기능이 없다. 그래서 다음과 같은 방법을 사용했다.

• git hook 작성
• 스마트폰에는 GitSync 설치
• Logseq graph를 GitHub와 동기화

Logseq 리포지토리는 Private로 두었다.

---

2. Quartz를 이용한 퍼블리시 구조

2.1 공개 문서와 개인 문서 문제

Logseq에는 개인 문서와 공개 문서가 함께 들어 있었다. 이 중에서 공개할 문서만 골라 Quartz 사이트로 발행하려 했다.

이 구조를 선택한 이유는 다음과 같다.

• 일부 문서는 공개할 수 없다.
• 그렇다고 개인 문서와 공개 문서를 완전히 분리하는 것은 관리가 번거롭다.

그래서 하나의 저장소 안에서 공개 폴더만 발행하는 구조를 만들었다.

2.2 Quartz 빌드 흐름

Quartz 리포지토리는 Public으로 만들었다. 여기에서 Logseq 리포지토리를 서브모듈로 연결할지, git clone으로 가져올지 고민했다.

결국 git clone 방식을 사용했다.

전체 흐름은 다음과 같았다.

1. 로컬에서 Logseq로 공개 폴더에 문서를 작성한다.
2. git hook을 통해 Logseq 리포지토리에 자동 커밋된다.
3. GitHub Action이 Quartz 리포지토리를 트리거한다.
4. Quartz 리포지토리는 Logseq 리포지토리를 임시 폴더로 clone한다.
5. 발행 폴더만 선택해 Quartz로 빌드한다.

npx quartz build --serve -d publish-folder

2.3 발생한 문제

문서를 clone할 때 파일 날짜가 현재 시간으로 바뀌는 문제가 있었다. 그래서 모든 문서에 프론트매터로 날짜를 명시해야 했다.

---

3. Logseq에서 Obsidian으로 이동

Logseq는 가볍고 빠르지만 불편한 점도 있었다.

특히 글머리 기호를 제거하기 어려운 구조였다. 그래서 결국 Obsidian으로 옮기게 되었다.

Obsidian을 선택한 이유는 다음과 같다.

• 일반 마크다운 문서 구조
• 다양한 Git 플러그인
• 자동 push 가능

이 시점에서 블로그 시스템도 다시 고민하게 되었고, 블로그 엔진은 Astro로 결정했다.

---

4. 디렉토리 구조 재설계

나는 보통 컴퓨터에서 디렉토리를 다음과 같이 나누어 관리한다.

dev
workspace

• dev → 개발 도구
• workspace → 실제 자료

하지만 이번 프로젝트에서는 툴과 문서를 완전히 분리하는 방식이 불편했다.

그래서 hub 디렉토리를 새로 만들었다.

4.1 초기 구조

hub
  quartz
  astro

하지만 이것도 완전히 마음에 들지 않았다.

4.2 최종 구조

결국 다음과 같은 구조로 정리했다.

dev/
  quartz
  astro

workspace/
  obsidian-vault

hub/
  quartz (submodule)
  astro (submodule)

이 구조의 장점은 다음과 같다.

• dev → 개발 환경
• workspace → 문서 관리
• hub → 프로젝트 묶음 관리

---

5. GitHub 리포지토리 구조

GitHub에는 다음과 같이 리포지토리를 구성했다.

• Obsidian Vault → Private
• Quartz → Public
• Astro → Public

예전에는 Quartz 리포지토리가 Vault를 가져와 발행하는 구조였다. 하지만 지금은 반대로 바뀌었다.

5.1 새로운 구조

이제는 Vault에서 Quartz 리포지토리를 서브모듈로 가져오는 구조다.

그리고 GitHub Action을 통해 Quartz 사이트를 빌드한다.

마찬가지로 Astro도 Vault 리포지토리를 기반으로 Cloudflare Pages에 연결해 배포한다.

---

6. 자동화 흐름

현재 자동화 흐름은 다음과 같다.

1. Obsidian에서 글 작성
2. 자동 git push
3. GitHub Action 실행
4. Quartz와 Astro 사이트 자동 배포

자동화 자체는 매우 안정적으로 작동한다.

---

7. Astro에서 발생한 문제

Quartz는 Obsidian 스타일 문서를 기준으로 설계된 도구이기 때문에 문제가 없었다.

하지만 Astro에서는 문제가 발생했다. Obsidian 문서 포맷이 Astro의 콘텐츠 구조와 맞지 않아 빌드 에러가 자주 발생했다.

---

8. Decap CMS 도입

이 문제를 해결하기 위해 Astro에는 Decap CMS를 설치했다.

이후 구조는 다음과 같이 바뀌었다.

• Decap CMS에서 작성한 문서 → Vault 리포지토리로 커밋
• Obsidian → git pull로 동일 문서 확인

즉

• Obsidian → 로컬 작성 도구
• Decap → 웹 작성 도구

두 시스템을 함께 사용할 수 있게 되었다.

---

9. 현재 시스템

지금의 구조는 다음과 같다.

Obsidian
   ↓
Vault (private repo)
   ↓
GitHub Actions
   ↓
Quartz (wiki)
Astro (blog)
   ↓
Cloudflare Pages

이렇게 해서 개인 위키와 블로그가 동시에 자동으로 배포되는 시스템을 만들게 되었다.