Cloudflare Pages로 문서 사이트 배포하기(VitePress)
이 저장소의 튜토리얼은 VitePress로 정적 사이트를 빌드합니다. 예: notionnext.tangly1024.com.
yarn export로 만드는 블로그 정적 사이트와 다릅니다. 문서 사이트에는NOTION_PAGE_ID가 필요하지 않습니다.
조직 저장소 권장 방식: GitHub Actions 배포(CF Git 연결 불필요)
GitHub 조직 아래의 저장소는 Cloudflare에서 Connect Git을 사용할 때 권한, 설치 범위, 저장소 목록 문제가 자주 발생합니다. 더 안정적인 방식은 다음입니다.
GitHub가 빌드 담당 -> API로 Cloudflare Pages에 업로드. Cloudflare Git 통합은 거치지 않습니다.
최초 준비
1. Cloudflare에서 Pages 프로젝트 만들기(빈 프로젝트 가능)
Cloudflare 콘솔 -> Workers and Pages -> Create -> Pages -> Upload assets로 이동합니다. 먼저 작은 파일 하나를 임시로 업로드해 프로젝트 생성을 완료합니다. 프로젝트 이름 예:
notionnext-docs이 이름은 나중에 배포 명령에서 사용하므로 기록해 둡니다.
또는 로컬에서 이미 wrangler login을 완료했다면 다음 명령을 사용할 수 있습니다.
npx wrangler pages project create notionnext-docs --production-branch=main2. API Token 만들기
Cloudflare -> My Profile -> API Tokens -> Create Token으로 이동합니다. Edit Cloudflare Workers 템플릿을 사용하거나 아래 권한을 직접 설정합니다.
| 권한 | 수준 |
|---|---|
| Account -> Cloudflare Pages | Edit |
| Account -> Account Settings | Read |
생성된 Token을 복사합니다. 이 값은 한 번만 표시됩니다.
Workers and Pages 개요 페이지 오른쪽에서 Account ID를 복사할 수 있습니다.
3. GitHub Secrets 설정(조직 또는 저장소)
저장소가 조직 아래에 있다면 조직에 설정하는 것을 권장합니다. 조직 Settings -> Secrets and variables -> Actions 또는 해당 저장소 Settings -> Secrets and variables -> Actions에서 설정합니다.
| Secret 이름 | 내용 |
|---|---|
CLOUDFLARE_API_TOKEN | 이전 단계의 API Token |
CLOUDFLARE_ACCOUNT_ID | Cloudflare Account ID |
선택 사항 Variables(민감 정보 아님):
| Variable 이름 | 내용 |
|---|---|
CLOUDFLARE_PAGES_PROJECT_NAME | Pages 프로젝트 이름. 기본값 notionnext-docs |
조직 저장소라면 Settings -> Actions -> General에서 Actions 사용이 허용되어 있는지 확인하고, 조직 정책이 workflow에 secrets 전달을 막고 있지 않은지도 확인하세요.
4. 저장소에 포함된 Workflow 활성화
이 저장소에는 .github/workflows/deploy-docs-site.yml이 포함되어 있습니다.
main으로 push되고docs/**,.vitepress/**등이 변경되면 자동으로yarn docs:site:build를 실행하고 배포합니다.- GitHub Actions 페이지에서 수동으로 Run workflow를 실행할 수도 있습니다.
처음 workflow 파일이 포함된 push 이후 Actions에서 **Deploy docs site (VitePress)**가 성공하는지 확인하세요.
5. 커스텀 도메인 연결
Cloudflare Pages 프로젝트에서 진행합니다. Git 연결과는 무관합니다.
Custom domains -> notionnext.tangly1024.com 추가. DNS가 Cloudflare에 있다면 보통 CNAME이 자동으로 추가됩니다.
방식 비교
| 방식 | 조직 저장소 | 설명 |
|---|---|---|
| GitHub Actions + wrangler(권장) | 호환성 좋음 | API Token만 필요하며 CF GitHub App 설치 불필요 |
| Cloudflare Connect Git | 문제 잦음 | 조직에 Cloudflare App 설치와 저장소 권한 부여 필요 |
로컬 wrangler pages deploy | 수동 | 디버깅에는 적합하지만 일상 자동 업데이트에는 부적합 |
그래도 Connect Git을 사용하고 싶다면(선택 점검)
- GitHub Organization Settings -> GitHub Apps에서 Cloudflare Workers and Pages를 설치하고 notionnext-org/NotionNext 접근을 허용합니다.
- 조직 Third-party access 정책이 해당 App을 허용해야 합니다.
- Cloudflare 쪽에서 조직 저장소 접근 권한이 있는 계정으로 로그인하고 GitHub 권한을 다시 부여합니다.
대부분의 경우 위의 Actions 방식을 직접 사용하는 편이 더 안정적입니다.
로컬 개발과 빌드
yarn
yarn docs:site:dev # http://localhost:5173
yarn docs:site:build # outputs .vitepress/dist
yarn docs:site:preview로컬 수동 업로드. Actions와 같은 명령입니다.
yarn docs:site:build
npx wrangler pages deploy .vitepress/dist --project-name=notionnext-docs먼저 npx wrangler login이 필요합니다.
Cloudflare Connect Git 참고(개인 저장소)
| 설정 항목 | 값 |
|---|---|
| 빌드 명령 | yarn install && yarn docs:site:build |
| 출력 디렉터리 | .vitepress/dist |
| Node | 20 |
조직 저장소라면 위의 Actions 흐름을 더 권장합니다.
배포 범위
.vitepress/config.mts를 참고하세요. 온라인 사이트는 user-guide/, developer/, community/, 루트 디렉터리의 주요 진입 페이지를 배포합니다. 루트 README는 저장소 디렉터리 설명용이므로 VitePress에 포함되지 않습니다.
문서 댓글(Giscus, 선택)
빌드 시 환경 변수를 주입하면 튜토리얼 페이지 하단에 문서 피드백이 표시됩니다. GitHub Discussions와 동기화됩니다.
| 이름 | 유형 | 설명 |
|---|---|---|
VITE_GISCUS_REPO_ID | Secret | R_kgDOGHdxTw(notionnext-org/NotionNext) |
VITE_GISCUS_CATEGORY_ID | Secret | DIC_kwDOGHdxT84CBR2I(Discussions category General) |
VITE_GISCUS_ENABLED | Variable | false로 설정하면 댓글 영역 비활성화 |
조직 저장소 Actions 배포 시 보통 GitHub Secrets에 이미 설정되어 있습니다. 자세한 내용은 maintain-docs.md와 루트 디렉터리 .env.docs.example을 참고하세요.
관련
- WEBSITE.md
- cloudflare-pages.md - 블로그
yarn export정적 사이트