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 블로그 글로 정규화한다.

1. 누락된 frontmatter를 보정한다.
2. 파일 경로에서 category와 tag를 파생한다.
3. slug가 없으면 경로 기반 slug를 생성한다.
4. Obsidian callout을 Docusaurus admonition으로 변환한다.
5. wiki link를 실제 블로그 링크로 변환한다.
6. draft: true 글은 검색 인덱스에서 제외한다.
7. 공개 글을 모아 static/posts.json을 생성한다.

이 방식 덕분에 작성자는 문서 내용에 집중하고, 배포 전 형식 정리는 스크립트가 담당한다.

운영 방식

파일 경로는 정보 구조의 기준이다. 예를 들어 posts/platform/obsidian-blog-pipeline.md는 platform 카테고리와 태그를 자동으로 얻는다. 글이 많아져도 폴더 구조만 보면 어떤 주제를 다루는지 알 수 있다.

slug는 직접 지정할 수 있지만, 지정하지 않아도 경로 기반으로 생성된다. 공개 URL을 직접 제어해야 하는 글만 slug를 명시하고, 일반 글은 파일 경로를 따른다.

draft는 공개 여부를 나누는 운영 스위치다. draft: true인 글은 Docusaurus 빌드 대상에는 남아 있을 수 있지만, 블로그 검색 인덱스와 공개 목록에서 제외하는 기준으로 사용한다.

앞으로의 개선 방향

다음 단계는 파이프라인을 더 신뢰할 수 있게 만드는 것이다. slug 충돌을 더 강하게 감지하고, 깨진 wiki link를 리포트로 남기며, 글 품질 체크를 CI에 붙일 수 있다. 최종 목표는 글을 작성하는 순간부터 배포 가능한 기술 문서가 되는 흐름이다.