개인 기술 블로그는 처음에는 Markdown 몇 개와 정적 사이트 생성기로 충분합니다. 하지만 글이 쌓이면 다음 요구가 동시에 생깁니다.
- Obsidian에서 편하게 작성하고 싶다.
- 공개 여부를 원고마다 안전하게 통제하고 싶다.
- 검색, 태그, 시리즈, RSS, sitemap을 제공하고 싶다.
- 댓글과 반응 같은 외부 상태도 일부 반영하고 싶다.
- 서버와 데이터베이스는 운영하고 싶지 않다.
- 빌드 결과와 원고의 불일치를 만들고 싶지 않다.
이 위키는 이 문제를 Markdown을 유일한 원본으로 유지하는 정적 컴파일 파이프라인으로 풀었습니다.
네 개의 경계를 먼저 나눈다
저장소는 다음 네 층으로 구분합니다.
| 영역 | 역할 | 변경 방식 |
|---|---|---|
content/ | 사람이 작성하는 Markdown 원고 | 직접 편집 |
src/ | 원고를 읽고 탐색·렌더링하는 애플리케이션 | 코드 변경 |
generated/, public/ | 지표, sitemap, feed 같은 파생 데이터 | 스크립트로 재생성 |
docs/ | GitHub Pages에 배포할 완전 정적 산출물 | 전체 빌드로 재생성 |
핵심은 content/와 나머지 영역의 권위가 다르다는 점입니다. 원고는 사람이 관리하는 정본이고, 나머지는 원고와 코드에서 다시 만들 수 있는 결과입니다.
이 경계를 명확히 하지 않으면 생성된 파일을 사람이 수정하거나, 원고와 검색용 JSON이 서로 다른 내용을 갖는 문제가 생깁니다.
전체 빌드 흐름
flowchart LR A[content/**/*.md<br/>Obsidian 원고] --> B[Frontmatter·경로 검증] B --> C[외부 반응 지표 갱신] C --> D[Sitemap·RSS·Atom 생성] D --> E[Vite raw import] E --> F[공개 Post 모델 변환] F --> G[TanStack Start prerender] G --> H[Preview HTTP smoke test] H --> I[docs/ GitHub Pages 산출물] I --> J[GitHub Pages 배포]
생성 단계는 콘텐츠 검증, 외부 지표 갱신, sitemap과 feed 생성 순으로 진행됩니다. 애플리케이션은 Vite의 raw import로 Markdown을 정적으로 묶고, 같은 변환 규칙을 사용해 공개 post 모델을 만듭니다. 이후 모든 라우트를 prerender하고 실제 HTTP 제공 상태를 smoke test한 뒤 docs/를 배포합니다.
중간 posts.json을 만들지 않는다
정적 블로그에서 흔히 사용하는 구조는 Markdown을 읽어 posts.json을 생성하고, 애플리케이션이 그 JSON을 다시 읽는 방식입니다.
구현은 단순하지만 두 가지 문제가 있습니다.
- Markdown과 JSON 중 무엇이 진짜 원본인지 경계가 흐려집니다.
- 생성 스크립트와 애플리케이션의 해석 규칙이 달라질 수 있습니다.
이 위키에서는 앱이 /content/**/*.md를 직접 정적 import합니다. 별도의 글 데이터베이스나 중간 JSON을 만들지 않습니다.
이 선택의 장점은 명확합니다.
- 원고의 SSOT가 유지됩니다.
- 개발 서버와 production build가 같은 원고를 읽습니다.
- post 변환 로직을 sitemap과 feed 생성에서도 재사용할 수 있습니다.
- 공개 필터, URL, 제목, 날짜 해석이 여러 경로에서 어긋날 가능성이 줄어듭니다.
물론 Markdown 전체가 번들 입력이 되므로 글 수와 렌더러가 커질수록 빌드 시간과 bundle size를 관찰해야 합니다. 하지만 현재 규모에서는 단순성과 일관성이 더 큰 가치였습니다.
공개는 opt-in이어야 한다
개인 vault에는 공개 글과 비공개 메모가 함께 존재할 수 있습니다. 따라서 “비공개라고 표시한 글만 제외”하는 방식은 위험합니다. 표시를 빠뜨리면 그대로 공개되기 때문입니다.
이 위키는 반대로 동작합니다.
---
title: 공개할 글
date: 2026-07-24
category: Backend/DevOps
tags: [Architecture]
public: true
---public: true가 명시된 글만 최종 post 목록에 포함됩니다. 필드가 없거나 값이 다르면 사이트에서 제외됩니다.
이 원칙은 공개 여부를 fail-open이 아니라 fail-closed로 만듭니다. 원고를 vault에 저장하는 행위와 인터넷에 공개하는 행위가 분리됩니다.
본문 일부도 비공개일 수 있다
글 전체는 공개하지만 작업 메모나 개인적인 맥락만 제외하고 싶은 경우도 있습니다. 이를 위해 private block과 private callout을 빌드 과정에서 제거합니다.
<!-- private -->
이 영역은 공개 산출물에서 제거된다.
<!-- /private -->다만 제거 로직만 믿어서는 안 됩니다. 정규식이나 parser는 중첩된 문법, 잘못 닫힌 블록, 새로운 표기법에서 실패할 수 있습니다.
더 안전한 방식은 두 단계입니다.
- 입력 단계에서 공개를 opt-in으로 제한한다.
- 생성된 HTML과 feed를 다시 검사해 private marker, 금지 패턴, 민감정보가 남지 않았는지 확인한다.
원고 검증과 최종 산출물 누출 검사는 다른 문제입니다.
외부 상태를 정적으로 캡처한다
댓글은 Giscus를 통해 브라우저에서 동적으로 표시할 수 있습니다. 하지만 트렌딩 정렬에 댓글과 반응을 사용하려면 빌드 시점에도 해당 상태가 필요합니다.
이 위키는 GitHub Discussions API의 결과를 generated/postMetrics.json에 저장합니다. 정적 사이트는 이 캐시를 읽어 최근 댓글, 반응, 활동 시점 등을 기준으로 정렬합니다.
여기서 중요한 설계 판단은 외부 API를 런타임 의존성으로 만들지 않는 것입니다.
- API가 정상이라면 최신 지표를 정적 산출물에 반영합니다.
- 토큰이나 설정이 없다면 빈 지표를 생성합니다.
- 지표가 없으면 최신 글 순으로 퇴화합니다.
- 사이트 자체의 빌드와 조회는 계속 동작합니다.
이것은 기능을 제거하는 fallback이 아니라, 핵심 가용성을 외부 부가기능과 분리하는 graceful degradation입니다.
하나의 변환 함수를 여러 산출물이 공유한다
정적 출판 시스템에서 자주 발생하는 버그는 화면에는 글이 보이는데 sitemap에는 없거나, RSS URL과 실제 라우트가 다른 경우입니다.
이를 막으려면 다음 산출물이 같은 post 모델을 공유해야 합니다.
- 웹 애플리케이션의 글 목록
- 글 상세 라우트
- 검색과 태그
- sitemap
- RSS와 Atom feed
- 트렌딩 지표 매핑
공개 필터와 URL 생성 규칙을 각 스크립트가 따로 구현하면 시간이 지날수록 반드시 갈라집니다. 작은 중복처럼 보여도 출판 시스템에서는 canonical URL과 공개 범위를 결정하는 핵심 계약입니다.
validator와 runtime parser는 같아야 한다
현재 구조에서 가장 주의해야 할 경계는 frontmatter입니다.
검증 스크립트가 완전한 YAML parser를 사용하고, 런타임이 제한된 자체 parser를 사용한다면 같은 파일을 다르게 해석할 수 있습니다. 예를 들어 복잡한 배열, 따옴표, multiline string, 특수문자가 한쪽에서는 통과하고 다른 쪽에서는 깨질 수 있습니다.
이 문제는 “검증이 있으니 안전하다”는 착각을 만듭니다. 실제로는 validator가 검사한 데이터와 앱이 사용하는 데이터가 다를 수 있습니다.
해결 방법은 둘 중 하나입니다.
- validator와 runtime이 동일한 parser와 변환 함수를 사용한다.
- 양쪽 구현을 유지해야 한다면 동일 fixture를 넣고 parity test를 수행한다.
검증의 목적은 파일 형식을 검사하는 것이 아니라 실제 배포될 해석 결과를 보장하는 것입니다.
무엇을 검증해야 하는가
콘텐츠 단계에서는 다음을 검사합니다.
- 공개 글의 제목 존재 여부
- 날짜 형식
- category와 tags
- 공개 URL 중복
- 시리즈 순서의 유효성과 중복
- 상대 이미지의 공개 경로
- private marker와 금지 패턴
애플리케이션 단계에서는 다음이 필요합니다.
- TypeScript strict check
- Markdown 변환 unit test
- 공개 필터 fixture
- sitemap, feed, route의 URL parity
- 전체 production build
- prerender된 페이지 수의 급격한 변화
- preview HTTP smoke test
- 주요 JavaScript chunk 크기와 빌드 시간 추이
정적 사이트라고 해서 운영 검증이 단순한 것은 아닙니다. 서버 장애 대신 잘못 생성된 산출물이 주요 장애가 됩니다.
이 구조의 트레이드오프
장점:
- 서버와 데이터베이스가 필요 없습니다.
- Markdown이 유일한 원본으로 남습니다.
- Git diff만으로 원고와 코드 변경을 검토할 수 있습니다.
- 공개 범위가 명시적입니다.
- 배포 산출물을 로컬과 CI에서 재현할 수 있습니다.
- 외부 API 장애가 사이트 가용성으로 전파되지 않습니다.
비용:
- 글과 렌더러가 늘면 빌드 비용이 증가합니다.
- 모든 공개 콘텐츠가 정적 번들 입력이 됩니다.
- 동적인 개인화와 실시간 지표에는 적합하지 않습니다.
- parser와 생성기 사이의 계약을 계속 테스트해야 합니다.
- 배포 전 민감정보 검사가 중요합니다.
결론
정적 지식 출판 시스템의 핵심은 프레임워크 선택이 아닙니다.
- 원고와 산출물의 권위를 분리하고
- Markdown을 SSOT로 유지하며
- 공개를 opt-in으로 만들고
- 모든 공개 산출물이 같은 변환 규칙을 공유하고
- 외부 상태는 정적으로 캡처하되 실패 시 핵심 기능을 유지하고
- 최종 배포물을 실제 HTTP 수준에서 검증하는 것입니다.
정적 사이트는 운영할 서버를 없애줍니다. 대신 빌드 파이프라인 자체가 출판 서버가 됩니다.