이 글은 “잘 쓰는 법”보다, 쓰고, 고치고, 배포하는 흐름 전체를 어떻게 설계했는지에 대한 기록이다.

내가 만들고 싶었던 건 딱 하나였다.

옵시디언에 글을 쓰면, 그 글이 곧 블로그 배포로 이어지는 것.
즉 옵시디언이 Single Source of Truth(SSOT)가 되는 글쓰기 시스템이다.

내가 가장 원했던 요구사항

요구사항은 여러 상황이 겹치며 또렷해졌다.

  1. 개발자로서 내가 마음대로 실험하고 조작할 수 있는 개인 웹사이트가 필요했다.
    플랫폼형 블로그로는 내가 원하는 실험을 하기 어렵고, 결국 “내가 통제할 수 있는 환경”이 필요했다.

  2. 옵시디언이 SSOT가 되어야 했다.
    옵시디언은 지금 내 생각과 메모가 쌓이는 주 도구다.
    로컬에 저장되고, 클라우드에 덜 의존하고, 내가 쓴 것을 내가 소유하고 통제한다는 감각이 좋았다.

  3. 마찰이 낮아야 했다.
    나는 글을 발행한 뒤에도 자주 고친다. 그게 더 자연스럽고 바람직하다고 생각한다.
    그런데 글이 두 군데에 있으면 수정도 두 번 해야 한다.
    원본은 옵시디언에 있고, 복제본은 블로그 프로젝트 안에 있으면 결국 옵시디언도 고치고 블로그도 고쳐야 한다.

그래서 “옵시디언에서 글을 작성하면 그것이 곧 배포가 되어야 한다”가 결정적 요구사항이 됐다.
나머지는 따라오는 조건이었다.

과거 시도: 블로그를 만들었지만 SSOT가 아니었다

예전에도 블로그를 만든 적은 있었다. 보통은 이런 식이었다.

  • 시중에 많이 쓰는 블로그 프로젝트를 포크해서 시작하거나
  • 템플릿을 가져와서 커스터마이징하며 운영하거나

그런데 콘텐츠가 SSOT가 아니었다.

내가 글을 쓰는 곳은 (당시엔 노션, 지금은 옵시디언)인데, 블로그를 운영하려면 글을 “블로그용”으로 따로 가공해서 넣어야 했다.
그리고 그 뒤에 수정이 일어나면, 결국 두 군데를 고쳐야 했다.

  • 옵시디언의 원본 수정
  • 블로그 프로젝트 안의 복제본 수정

이 구조는 글이 쌓일수록 비용이 폭발한다.
그래서 “옵시디언과 반드시 연동되어야 한다”가 이번 프로젝트의 출발점이 됐다.

결정적 계기: 미니PC가 생기면서 ‘실행 환경’이 됐다

어느 순간 미니PC를 개인 용도로 활용할 수 있게 됐다.
나는 원래 새로운 시도를 가치 있게 여기는 편이라, “그럼 셀프 호스팅을 해볼까?”가 자연스럽게 떠올랐다.

특히 예전에 ‘커피 한 잔’ 서비스를 만든 분이 집에 있는 컴퓨터로 서버를 돌렸다는 이야기가 기억에 남아 있었다.
그게 “나도 할 수 있겠는데?”로 이어졌다.

미니PC는 내 요구사항을 현실로 만드는 실행 환경이 되어줬다.

왜 Eleventy(11ty)였나

정적 사이트 생성기(SSG) 중에서 내가 찾던 조건은 간단했다.

  • 가볍게 시작할 수 있을 것
  • 빌드가 빠를 것
  • 블로그라는 목적에 과하지 않을 것

블로그는 대체로 복잡한 UI나 거대한 재사용성이 필요한 제품이 아니다.
나는 처음부터 큰 프레임워크를 얹기보다, 작게 시작해서 필요해질 때만 추가하는 쪽이 더 좋은 전략이라고 생각했다.

내가 조사했을 때 Eleventy는 “단순하지만 강력한” 쪽에 가까웠고, 초반엔 배포가 3초도 안 걸렸던 기억이 있다.
지금은 글이 늘어나서 6초 정도 걸리지만, 배포는 백그라운드로 실행할 수 있어서 큰 문제가 되진 않는다.

실제 파이프라인: “옵시디언에 쓰면 배포된다”가 동작하는 방식

이 글의 핵심인데, 처음 버전에는 이 얘기가 빠져 있었다.
내 시스템은 시간이 지나며 3단계로 진화했다.

한 장 요약

flowchart LR
  A["Obsidian vault<br/>Blog Posts 폴더"] -->|복사/동기화| B["블로그 빌드 프로젝트<br/>(11ty)"]
  B -->|build| C["_site 정적 산출물"]
  C -->|배포 복사| D["Mini PC 웹서버 디렉토리"]
  D --> E["외부 접속"]

v1. 쉘 스크립트로 직접 배포하던 시절

처음엔 내가 직접 쉘 스크립트를 실행했다. 스크립트가 하는 일은 단순했다.

  1. 옵시디언 vault의 특정 폴더(예: Blog Posts/) 아래 마크다운과 에셋을
  2. Eleventy 블로그 프로젝트로 전부 복사한다
  3. 블로그 프로젝트에서 빌드 스크립트를 실행한다
  4. 빌드된 산출물(_site)을 미니PC 웹서버 디렉토리로 다시 복사한다

이 방식은 구현이 쉽고 즉시 동작했다. 하지만 점점 불편해졌다.

  • 매번 터미널로 실행해야 한다
  • OS별(맥/윈도우/모바일) 차이를 계속 처리해야 한다
  • 로직이 커질수록 스크립트가 관리하기 힘들어진다

v2. 옵시디언 플러그인으로 배포하다

"매번 터미널을 열지 말고, 옵시디언 안에서 끝내면 어떨까?"

배포를 옵시디언 내부 동작으로 만들었다. 로컬 플러그인을 만들어서 맥북과 윈도우 모두에서 동작하게 했고, 이제 버튼 한 번으로 배포가 됐다.

마찰이 확실히 줄었다. 글 쓰다가 바로 배포하고, 다시 글 쓰기로 돌아갈 수 있었다.

그런데 모바일이 문제였다.

  • 모바일에서는 OS 접근이 제한적이다
  • 쉘 스크립트 실행 같은 방식이 안 된다
  • 로컬에서 빌드하고 복사하는 흐름이 막힌다

v3. 미니PC에 API 서버를 만들고, 플러그인이 호출하게 하다

핵심 아이디어는 "배포 실행의 주체를 미니PC로 옮기는 것"이었다.

  • 옵시디언 플러그인은 단순히 API를 호출만 한다
  • 미니PC가 "복사 → 빌드 → 배포"를 모두 처리한다

이렇게 바꾸니 모바일에서도 똑같이 동작했다. OS 종류가 중요하지 않게 됐다. 그냥 HTTP 요청만 보내면 됐다.

이 과정에서 깨달은 건, 문제를 "어디서 실행할 것인가"로 재구성하니 해법이 명확해졌다는 것이다.

콘텐츠 백업과 통계를 위한 추가 흐름

또 한 가지 중요한 흐름이 있다.

  • 순수 콘텐츠(마크다운 파일)와 에셋 파일은 별도 레포지토리에 복제해서 커밋한다
  • 배포 파이프라인 안에서 이 커밋이 같이 실행된다

이건 단순 백업을 넘어서, 내가 글을 얼마나 쓰는지 추적하기 위한 기반이 됐다.

셀프 호스팅: 실험할 수 있는 환경을 갖추다

미니PC로 셀프 호스팅을 선택한 이유는 단순히 비용 때문이 아니었다.

  • 내가 통제할 수 있는 환경
  • 실패해도 괜찮은 실험 공간
  • 과정 자체를 배움으로 가져갈 수 있는 기회

클라우드 서비스도 좋지만, 내 손으로 직접 만지고 고치면서 배우는 게 내 성향에 맞았다. 도메인 연결, 공유기 설정 같은 것들이 처음엔 낯설었지만, 하나씩 해결하면서 "내 서버"라는 감각이 생겼다.

삽질 기록: 매끄럽게만 흘러가진 않았다

처음에는 “마크다운 변환 라이브러리가 다 해주겠지”라고 생각했다. 그런데 옵시디언에는 옵시디언 전용 문법이 꽤 있었다.

1) 옵시디언 문법은 일반 마크다운이 아니었다

처음엔 "마크다운 변환 라이브러리만 쓰면 되겠지"라고 생각했다. 그런데 옵시디언에는 위키 링크([[다른 글]])나 임베드(![[이미지.png]]) 같은 고유 문법이 있었다.

일반 마크다운 파서는 이걸 모른다. 그대로 렌더링하면 [[다른 글]]이 그대로 텍스트로 나온다.

"아, 이건 내가 직접 처리해야 하는구나."

결국 옵시디언 문법을 일반 마크다운/HTML로 변환하는 로직을 직접 만들었다. 생각보다 예외 케이스가 많았지만, 하나씩 해결하면서 옵시디언 파서 동작 방식을 이해하게 됐다.

2) Mermaid는 '있으면 좋다'가 아니라 '운영 난이도'였다

GitHub 마크다운 뷰어의 Mermaid가 부러웠다. 확대도 되고, 드래그도 되고, UX가 훌륭했다.

"나도 저렇게 만들어야지" 하고 라이브러리를 붙였다. 그런데 다이어그램 크기가 커지면 깨지고, 브라우저마다 동작이 달랐고, 스타일링도 예상과 달랐다.

고치는 시간이 점점 늘어났다. 그러다 깨달았다. "나는 지금 Mermaid 다이어그램을 몇 개나 쓰고 있지?"

답은 거의 없었다. 그래서 삭제했다.

이 경험이 "작게 시작" 원칙을 체화시켰다.

  • 필요하면 나중에 만든다
  • 지금은 안정적이고 단순한 쪽을 택한다

3) "블로그면 당연히 있어야지"는 함정이었다

태그 기능도 그랬다.

"블로그엔 당연히 태그 시스템이 있어야지." 그래서 태그 페이지를 만들고, 태그별 필터링 기능을 붙였다.

그런데 글을 쓸 때 태그를 거의 안 달았다. 태그 페이지도 내가 거의 안 들어갔다.

"왜 안 쓰지?" 곰곰이 생각해보니, 내 글쓰기 방식은 태그보다는 폴더 구조에 더 맞았다. 기술 글은 tech/ 아래, 일상 기록은 log/ 아래. 이게 더 직관적이었다.

그래서 태그 시스템을 삭제하고, 최소한의 카테고리만 남겼다. 코드는 줄었고, 유지보수 부담도 사라졌다.

일부러 뺀 것, 대신 넣은 것

의도적으로 뺀 기능들

"블로그라면 있어야지" 하는 것들을 많이 뺐다.

  • 페이지네이션: 글이 많지 않은데 필요할까?
  • 댓글 시스템: 지금 당장 피드백 받는 채널이 있는가?
  • 검색 기능: 글이 10개도 안 되는데?
  • 정교한 스타일링: 디자인 시스템보다 콘텐츠가 먼저다

나중에 필요하면 추가하면 된다. 지금 없어도 글은 쓸 수 있다.

대신 내가 진짜 원해서 넣은 것들

반대로 "남들은 안 만들어도 나는 필요한" 기능도 있었다.

  • visibility 제어: 초안이나 개인적인 글을 목록에서 숨기기
  • 커스텀 URL 구조: 파일 경로와 독립적으로 URL을 자유롭게 설정
  • Git 기반 통계: 내 글쓰기 루틴을 추적하고 동기부여 받기

이런 기능들은 대중적인 블로그 템플릿에는 잘 없다. 하지만 내 SSOT 기반 글쓰기 흐름에는 핵심이었다.

콘텐츠와 "블로그 껍데기"를 분리한 이유

처음엔 단순한 동기였다. "이 블로그 템플릿을 나중에 공개하면 재미있겠다."

그러려면 내 개인적인 글과 블로그 시스템 코드가 섞여 있으면 안 됐다. 그래서 분리했다.

  • 블로그 레포: 렌더링, 템플릿, 빌드 파이프라인 (공개 가능)
  • 콘텐츠 레포: 내 글과 이미지 (개인용)

블로그 레포에는 .gitignore로 콘텐츠 폴더를 제외했다.

그런데 이 분리가 예상 밖의 보상을 줬다. Git 커밋 히스토리가 "순수하게 내 글쓰기만" 보여주게 됐다.

Git으로 글쓰기 통계를 만들었다

무라카미 하루키는 매일 일정 분량을 꼭 쓴다고 했다. 나도 그런 루틴을 만들고 싶었는데, 디지털 환경에서는 어떻게 추적할까?

그때 깨달았다. 글도 코드처럼 Git으로 관리하면, 변화가 모두 기록된다.

  • 언제 글을 썼는지 (커밋 날짜)
  • 얼마나 썼는지 (추가된 줄 수, 단어 수)
  • 얼마나 고쳤는지 (변경된 줄 수)

콘텐츠 레포를 별도로 분리했기 때문에, Git 히스토리가 "순수하게 내 글쓰기만" 보여준다. 이걸 기반으로 블로그에 통계 페이지를 만들었다.

  • 연속으로 글을 쓴 일수 (streak)
  • 하루에 쓴 단어 수
  • 최근 1개월, 3개월, 6개월의 글쓰기량

숫자가 보이니 동기부여가 됐다. "오늘은 안 쓰면 streak가 끊기는데?" 하는 생각이 글을 열게 만들었다. 글쓰기가 일회성 이벤트가 아니라, 측정 가능한 루틴이 됐다.

최종 구성: 단순하게, 그러나 내 것으로

결과적으로 만들어진 시스템은 이렇다.

  • Obsidian: 내가 글 쓰는 곳이자 SSOT
  • Obsidian 플러그인: 배포 버튼 하나로 모든 기기에서 동작
  • Eleventy: 가볍고 빠른 정적 사이트 생성
  • 미니PC: 빌드와 배포를 실행하는 서버이자, 실험 공간
  • 두 개의 레포: 블로그 껍데기와 콘텐츠를 분리해서 각자의 목적에 집중

화려하진 않지만, 내가 원하던 "쓰면 바로 배포되는" 흐름이 완성됐다. 그리고 이 과정에서 배운 것들이 결과물만큼이나 값졌다.

지금까지 해보며 얻은 것들

기술적인 배움

  • 문제를 재구성하면 해법이 보인다: 모바일 배포 문제를 "어디서 실행할 것인가"로 재정의하니 API 서버라는 답이 명확해졌다
  • 분리의 힘: 콘텐츠와 껍데기를 나누니 각자가 맡은 역할에 집중할 수 있었다
  • 과잉 엔지니어링을 경계하라: Mermaid 확대 기능, 태그 시스템처럼 "있으면 좋겠지만 지금 필요하지 않은" 것들을 과감히 빼는 연습

글쓰기에 대한 깨달음

  • SSOT가 무너지면 글쓰기는 습관이 아니라 노동이 된다: 두 곳을 고치는 순간 마찰이 생기고, 마찰은 지속을 방해한다
  • 통제권이 동기부여가 된다: 내 글이 내 서버에 있고, 내가 직접 만든 파이프라인을 통해 배포된다는 감각이 글쓰기를 더 즐겁게 만들었다
  • 추적이 루틴을 만든다: Git 기반 통계를 보니 글쓰기가 일회성 이벤트가 아니라 지속적인 활동으로 느껴졌다

앞으로

앞으로는 글과 글의 관계를 한눈에 볼 수 있는 도식 페이지 같은 것도 만들어보고 싶다. 하지만 그때도 원칙은 같다.

작게 시작하고, 진짜 필요해졌을 때만, 최소한으로 추가한다.