Starlight로 매뉴얼 만들기 #4 Cloudflare Pages로 배포하고 도메인 연결하기

프레임워크 Starlight Documentation Static Site
2 분 소요

#3까지 오면 로컬에서 보기 좋은 문서가 갖춰집니다. 하지만 localhost는 나만 볼 수 있습니다. 이번 글에서는 이 문서를 누구나 주소로 접속할 수 있게 내보냅니다.

이번 시리즈는 Starlight로 매뉴얼 만들기 6편입니다.

  • #1 설치부터 첫 문서까지
  • #2 사이드바와 검색 — 문서의 정보 구조 잡기
  • #3 콘텐츠 작성 — 코드블록, Mermaid, asides
  • #4 Cloudflare Pages로 배포하고 도메인 연결하기 ← 이번 글
  • #5 다국어와 버전 관리
  • #6 유지보수 — 검색, 접근성, 문서 문화

이번 글은 GitHub에 올리고, Cloudflare Pages에 연결해 빌드를 잡고, 커스텀 도메인을 붙이는 데까지 다루겠습니다.

GitHub에 올리기 #

빌드 결과물과 의존성은 저장소에 넣지 않도록 .gitignore부터 챙깁니다. Astro의 빌드 산출물은 dist 폴더입니다.

.gitignore 
dist/
node_modules/
.astro/

그다음 저장소를 초기화해 푸시합니다.

GitHub에 올리기 
git init
git add .
git commit -m "docs: 첫 문서"
git branch -M main
git remote add origin https://github.com/내계정/my-docs.git
git push -u origin main

Cloudflare Pages에 연결 #

Cloudflare 대시보드에서 Workers & Pages → Create → Pages → Connect to Git로 저장소를 선택합니다. Astro는 Node 프로젝트라 빌드 설정이 단순합니다.

항목값
프레임워크 프리셋Astro
빌드 명령npm run build
빌드 출력 디렉터리dist
환경 변수NODE_VERSION = 20

Node 버전은 로컬과 맞추는 것이 안전합니다. Save and Deploy를 누르면 첫 배포가 시작되고, 끝나면 프로젝트이름.pages.dev 주소가 생깁니다. 이후로는 main에 푸시할 때마다 자동으로 다시 빌드됩니다. #2에서 본 검색 색인도 이 빌드 단계에서 함께 만들어집니다.

커스텀 도메인 연결 #

pages.dev 주소 대신 직접 산 도메인을 붙입니다. Pages 프로젝트의 Custom domains → Set up a domain에서 도메인을 입력합니다. 다른 곳에서 DNS를 관리한다면 다음 레코드를 직접 넣습니다.

DNS 레코드 (하위 도메인) 
유형    이름     값
CNAME   docs     프로젝트이름.pages.dev

연결이 끝나면 HTTPS 인증서는 Cloudflare가 자동으로 발급하고 갱신합니다. 커스텀 도메인을 쓸 때는 astro.config.mjs의 site 값도 그 주소로 맞춰 줍니다. 검색과 사이트맵이 올바른 절대 주소를 쓰도록 하기 위해서입니다.

마무리 #

이번 글에서는 문서를 GitHub에 올리고, Cloudflare Pages에 연결해 Astro 빌드를 잡고, 커스텀 도메인까지 붙였습니다. 이제 문서는 진짜 주소를 갖고 인터넷에 떠 있습니다.

다음 편에서는 다국어와 버전 관리를 다룹니다. 하나의 문서를 여러 언어로 제공하고, 제품 버전이 올라갈 때 옛 문서를 어떻게 함께 유지할지 정리하겠습니다.

X