블로그 운영 구조
이 저장소는 Obsidian Vault의 content/를 Quartz v5로 빌드해 블로그로 공개한다.
운영에서 구분해야 할 상태는 두 가지다.
publish: Quartz 사이트에 표시할지 결정한다.commit: Git staging 대상으로 선택할지 결정한다.
두 속성은 독립적이다. publish: true 파일을 사이트에 포함하려면 결국 Git에 올려야 하지만, commit: true라고 해서 자동으로 공개되지는 않는다.
파일 형식별 관리 방식
| 파일 형식 | publish, commit 저장 위치 | Quartz 공개 조건 |
|---|---|---|
| Markdown | 원본 .md frontmatter | publish: true 이고 draft: true가 아닐 것 |
| Canvas | content/_publication/의 제어 Markdown | 제어 파일의 publish: true |
| Base | content/_publication/의 제어 Markdown | 제어 파일의 publish: true |
| Excalidraw | content/_publication/의 제어 Markdown | 제어 파일의 publish: true |
Canvas, Base, Excalidraw는 형식과 관계없이 동일한 공개 정책을 적용하기 위해 별도 제어 Markdown을 사용한다. 제어 파일은 [[Publication Manager Sync 플러그인]]이 자동으로 생성하고 정리한다.
주요 파일과 디렉터리
| 경로 | 역할 |
|---|---|
content/ | Quartz가 읽는 콘텐츠 루트 |
content/_publication/ | Canvas/Base/Excalidraw 공개 상태를 담는 기술적 제어 문서 |
PUBLICATION-MANAGER.base | 모든 지원 형식의 공개·커밋 상태를 편집하는 로컬 관리 화면 |
content/PUBLISHED-NOTES.base | 공개된 문서를 보기 위한 Base |
quartz.config.yaml | Quartz 플러그인과 사이트 기본 설정 |
quartz.ts | YAML로 표현하기 어려운 런타임 커스텀 조립 |
custom/ | 공개 필터, Cornell 렌더링, footer 등 커스텀 코드 |
tools/ | 제어 파일 동기화와 선택적 Git staging 도구 |
기본 운영 순서
- Obsidian에서 Markdown, Canvas, Base 또는 Excalidraw를 작성한다.
PUBLICATION-MANAGER.base에서 대상을 찾는다.- 사이트에 내보낼 파일은
publish를 켠다. - Git에 올릴 파일은
commit을 켠다. npm run stage:notes로 staging 예정 파일과 연결 asset을 확인한다.npm run stage:notes:apply로 선택된 파일만 staging한다.npx quartz build로 공개 결과를 검증한다.
로컬 미리보기가 필요하면 다음을 실행한다.
npx quartz build --serve공개 제외 정책
다음 폴더는 작업 중인 문서로 간주하고 Quartz가 무조건 무시한다.
content/archive/content/분류 전/content/claude code 활용/
이 폴더의 Markdown에 publish: true가 있어도 사이트에는 나오지 않는다. Canvas/Base/Excalidraw 자동 제어 대상에서도 제외된다.
Git 상태에 대한 주의
commit: false는 다음 staging 실행에서 선택하지 않는다는 뜻이다. 이미 Git에 커밋된 파일을 삭제하거나 GitHub에서 제거하지는 않는다.
Vault 전체를 staging하는 git add .은 commit: false 정책을 무시한다. 문서 커밋은 원칙적으로 stage:notes 도구를 사용한다.