배포와 운영

로컬 미리보기

npm run dev

http://localhost:3000 에서 열리고, content/ 의 파일을 저장하면 브라우저가 자동으로 갱신됩니다. Obsidian으로 편집하면서 이 창을 띄워두면 결과를 바로 확인할 수 있습니다.

Obsidian 설정

이 저장소의 content/ 폴더 자체를 볼트로 엽니다 (Obsidian → 폴더로 열기 → content 선택).

볼트 설정에서 맞춰야 할 것:

설정	값	이유
새 노트 위치	현재 폴더	폴더 분류가 유지됩니다
내부 링크 형식	짧은 경로	Quartz의 shortest 해석과 일치
위키링크 사용	켬	백링크·그래프뷰의 전제
첨부파일 위치	assets/ 하위 폴더	이미지가 노트 옆에 흩어지지 않게

.obsidian/ 폴더는 git과 빌드 양쪽에서 제외되어 있어 그대로 두면 됩니다.

배포

v5 브랜치에 push하면 GitHub Actions가 빌드해 Cloudflare Pages로 올립니다. 워크플로는 .github/workflows/deploy-wiki.yaml.

동작하려면 저장소 시크릿 두 개가 필요합니다:

• CLOUDFLARE_API_TOKEN — My Profile → API Tokens → Create Custom Token, 권한에 Account · Cloudflare Pages · Edit 하나만 부여합니다. (템플릿 중 Edit Cloudflare Workers 를 쓰라는 안내가 흔한데, 그건 Pages 배포에 필요 없는 권한까지 넓게 줍니다.)
• CLOUDFLARE_ACCOUNT_ID — npx wrangler whoami 출력 또는 대시보드 우측의 Account ID

Cloudflare Pages 프로젝트

프로젝트 이름은 yonggyu-llm-wiki, 주소는 https://yonggyu-llm-wiki.pages.dev 입니다. 이 이름은 세 곳에 같이 박혀 있으므로 바꿀 때는 함께 고쳐야 합니다.

위치	값
Cloudflare 프로젝트명	yonggyu-llm-wiki
deploy-wiki.yaml → projectName	yonggyu-llm-wiki
quartz.config.yaml → baseUrl	yonggyu-llm-wiki.pages.dev

baseUrl이 실제 주소와 다르면 검색·그래프뷰·OG 이미지 링크가 조용히 깨집니다.

프로젝트 생성은 wrangler로 합니다:

npx wrangler login
npx wrangler pages project create yonggyu-llm-wiki --production-branch v5
npx wrangler whoami   # Account ID 확인

두 가지 함정

• Direct Upload 프로젝트여야 합니다. 대시보드에서 “Connect to Git”으로 만들면 Cloudflare가 자체 빌드를 돌려 Actions의 업로드와 충돌합니다.
• production branch가 v5여야 합니다. Pages 기본값은 main이라, 그대로 두면 모든 배포가 preview로 잡히고 .pages.dev 본 주소가 갱신되지 않습니다. 워크플로의 branch: v5 값과 일치해야 합니다.

커스텀 도메인

지금은 @quartz-community/cname 플러그인을 꺼 두었습니다. 나중에 도메인을 붙이면 Cloudflare 프로젝트에 도메인을 연결하고, baseUrl을 그 도메인으로 바꾸면 됩니다.

본가(upstream) 업데이트 받기

이 저장소는 jackyzha0/quartz의 fork입니다.

git fetch upstream
git merge upstream/v5

충돌은 대개 quartz.config.yaml과 package.json에서 납니다 — 내 설정을 남기고 새 플러그인만 받아오면 됩니다. content/ 는 upstream에 없는 내용이라 충돌하지 않습니다.

관련

Meta · 작성 규약