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

프레임워크 Docusaurus Documentation Static Site
3 분 소요

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

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

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

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

GitHub에 올리기 #

빌드 결과물과 의존성은 저장소에 넣지 않도록 .gitignore부터 챙깁니다. create-docusaurus가 기본 .gitignore를 만들어 주지만, 핵심은 다음 세 가지입니다.

.gitignore 
/build/
/node_modules/
/.docusaurus/

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

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로 저장소를 선택합니다. Docusaurus는 Node 프로젝트라 빌드 설정이 단순합니다.

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

Node 버전은 로컬과 맞추는 것이 안전합니다. Save and Deploy를 누르면 첫 배포가 시작되고, 끝나면 프로젝트이름.pages.dev 주소가 생깁니다. 이후로는 main에 푸시할 때마다 자동으로 다시 빌드됩니다.

더 간단한 길 — deploy 명령 #

GitHub Pages를 쓴다면 Docusaurus가 배포 명령을 제공합니다. 먼저 docusaurus.config.js에 url, baseUrl, organizationName, projectName을 채운 뒤 실행합니다.

GitHub Pages로 한 번에 
npm run deploy

내 컴퓨터에서 빌드해 gh-pages 브랜치로 올리는 방식입니다. 팀이 함께 쓴다면 푸시 시 자동 빌드되는 Cloudflare 쪽이 사고가 적습니다.

커스텀 도메인 연결 #

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

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

연결이 끝나면 HTTPS 인증서는 Cloudflare가 자동으로 발급하고 갱신합니다. 커스텀 도메인을 쓸 때는 docusaurus.config.js의 url과 baseUrl도 그 도메인에 맞게 맞춰 줍니다.

마무리 #

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

다음 편에서는 다국어와 버전 관리를 다룹니다. Docusaurus가 가장 강한 영역으로, 둘 다 기본 기능으로 갖춰져 있습니다.

X