Obsidian 기반 기술블로그 파이프라인을 만든 이유
개발 기록은 작성할 때보다 다시 찾아 쓰고 공유할 때 가치가 커진다. 문제는 개인 지식 관리 도구와 공개 블로그가 요구하는 형식이 다르다는 점이다. Obsidian은 빠르게 연결하고 메모하기 좋지만, 그 문법을 그대로 정적 블로그에 올리면 링크, 콜아웃, 메타데이터가 깨지기 쉽다.
이 블로그는 그 간극을 줄이기 위해 만들었다. Obsidian에서는 작성 경험을 유지하고, 배포 단계에서는 Docusaurus가 안정적으로 빌드할 수 있는 문서로 정규화한다.
문제 상황
처음에는 글마다 title, date, slug, tags를 직접 관리했다. 글 수가 적을 때는 큰 문제가 아니었지만, 카테고리가 늘어나면서 반복 작업이 많아졌다.
- 파일 경로와 블로그 카테고리가 따로 관리되었다.
- Obsidian의
[[위키링크]]가 공개 블로그에서 의미 없는 텍스트가 되었다. > [!note]같은 콜아웃을 Docusaurus admonition으로 매번 고쳐야 했다.- 작성 중인 글을 배포 전에 제외하는 기준이 흔들렸다.
- 검색 페이지를 위해 공개 글 목록을 다시 가공해야 했다.
반복되는 작업을 사람이 기억하는 방식으로 해결하면 언젠가 실수한다. 그래서 글 작성 규칙을 코드로 옮겼다.
왜 Docusaurus를 선택했는가
Docusaurus는 기술 문서에 필요한 기능을 기본값에 가깝게 제공한다. Markdown/MDX 기반 작성 흐름, 사이드바와 라우팅, RSS/Atom, sitemap, prism 코드 하이라이트, 플러그인 생태계가 개인 기술블로그에 잘 맞았다.
특히 Mermaid와 KaTeX를 함께 사용할 수 있어 아키텍처 다이어그램과 수식을 글 안에서 자연스럽게 다룰 수 있다. 정적 사이트로 배포되므로 GitHub Pages와도 잘 맞는다.
sync-posts가 해결하는 문제
scripts/sync-posts.mjs는 Obsidian에서 작성한 Markdown을 Docusaurus 블로그 글로 정규화한다.
- 누락된 frontmatter를 보정한다.
- 파일 경로에서 category와 tag를 파생한다.
- slug가 없으면 경로 기반 slug를 생성한다.
- Obsidian callout을 Docusaurus admonition으로 변환한다.
- wiki link를 실제 블로그 링크로 변환한다.
draft: true글은 검색 인덱스에서 제외한다.- 공개 글을 모아
static/posts.json을 생성한다.
이 방식 덕분에 작성자는 문서 내용에 집중하고, 배포 전 형식 정리는 스크립트가 담당한다.
운영 방식
파일 경로는 정보 구조의 기준이다. 예를 들어 posts/platform/obsidian-blog-pipeline.md는 platform 카테고리와 태그를 자동으로 얻는다. 글이 많아져도 폴더 구조만 보면 어떤 주제를 다루는지 알 수 있다.
slug는 직접 지정할 수 있지만, 지정하지 않아도 경로 기반으로 생성된다. 공개 URL을 직접 제어해야 하는 글만 slug를 명시하고, 일반 글은 파일 경로를 따른다.
draft는 공개 여부를 나누는 운영 스위치다. draft: true인 글은 Docusaurus 빌드 대상에는 남아 있을 수 있지만, 블로그 검색 인덱스와 공개 목록에서 제외하는 기준으로 사용한다.
앞으로의 개선 방향
다음 단계는 파이프라인을 더 신뢰할 수 있게 만드는 것이다. slug 충돌을 더 강하게 감지하고, 깨진 wiki link를 리포트로 남기며, 글 품질 체크를 CI에 붙일 수 있다. 최종 목표는 글을 작성하는 순간부터 배포 가능한 기술 문서가 되는 흐름이다.