6강. Docusaurus 사이트를 GitHub Pages에 처음 배포하기

?1. 이번 강의에서 해결할 문제

첫 배포에서 저장소 이름과 baseUrl이 다르거나 Pages 원본이 잘못되면 CSS와 내부 링크가 깨집니다. 기존 설정을 덮어쓰기 전에 값과 workflow를 읽습니다.

✓2. 학습 목표

✓이 강의를 마치면

• Docusaurus url, baseUrl, 조직·프로젝트 설정을 검증합니다.
• Pages build artifact와 deploy job의 관계를 설명합니다.
• GitHub 웹에서 Actions 배포 원본과 실행 결과를 확인합니다.

◇3. 핵심 개념

Docusaurus는 npm run build로 build 디렉터리만 만들고 호스팅은 외부 서비스 책임입니다. 현재 workflow는 main push에서 source checkout→Node 설정→npm ci→build→Pages artifact 업로드→deploy 순서로 실행됩니다. 프로젝트 사이트라면 baseUrl에 저장소 이름이 포함되어야 합니다.

Docusaurus 공식 배포 문서의 URL 설정과 GitHub Pages 절차를 기준으로 합니다.

✎4. 단계별 실습

1. PowerShell

실행 위치: 저장소 루트

실행 전 확인: 파일을 새 예제로 교체하지 않습니다.

대상: 현재 설정과 workflow를 읽기 전용 검토

PowerShell

Select-String -Path docusaurus.config.js -Pattern "url:|baseUrl:|projectName:|organizationName:|trailingSlash:"
Get-Content .github\workflows\deploy-pages.yml
npm.cmd run build

예상 결과: URL 설정과 build/deploy job이 표시되고 로컬 빌드가 성공합니다.

2. GitHub 웹 화면

실행 위치: 저장소 Settings → Pages

실행 전 확인: workflow와 main 브랜치가 원격에 있는지 확인합니다.

대상: Build and deployment source

GitHub 웹 화면

1. Source를 GitHub Actions로 선택
2. Actions 탭에서 Pages workflow 열기
3. build와 deploy job 성공 확인
4. deployment의 page_url 열기

예상 결과: 두 job이 성공하고 프로젝트 Pages URL에서 사이트가 열립니다.

→5. 배포·운영 흐름이 동작하는 이유

build job은 소스와 의존성으로 정적 artifact를 만들고 deploy job은 Pages 전용 권한으로 그 artifact를 게시합니다. 분리된 job과 최소 권한은 빌드 실패가 게시 단계로 넘어가는 것을 막습니다.

!6. 자주 하는 실수와 안전한 해결법

!자주 하는 실수

• 실수: 기존 workflow를 복사 예제로 덮어씀 안전한 해결: 현재 action 버전과 권한을 읽고 필요한 변경만 PR로 제안합니다.
• 실수: 프로젝트 사이트에 baseUrl / 사용 안전한 해결: /REPOSITORY/ 형식을 확인합니다.
• 실수: 배포 토큰을 YAML에 직접 작성 안전한 해결: 공식 Pages action의 GITHUB_TOKEN 권한을 사용하고 실제 토큰을 커밋하지 않습니다.

✎7. 직접 실습

✎직접 실습

1. 현재 config 네 값과 예상 Pages URL을 비교합니다.
2. workflow의 build·artifact·deploy 단계를 화살표로 그립니다.
3. GitHub 웹에서 성공 job과 page_url 확인 항목을 기록합니다.

실습 기록에는 변경 SHA, 실행 위치, 확인 대상, 예상 결과와 실제 결과를 남기고 실제 토큰·비밀번호·SSH 개인 키·.env 내용은 포함하지 않습니다.

?8. 이해 점검 질문 3개

?이해 점검

1. Docusaurus의 책임은 build 이후 어디까지인가요?
2. Pages artifact는 두 job 사이에서 어떤 역할을 하나요?
3. 프로젝트 사이트의 baseUrl은 어떤 형태인가요?

■9. 핵심 요약

■핵심 요약

첫 Pages 배포는 정확한 URL 설정, 로컬 build, Actions source 선택, build·deploy job과 page_url 확인으로 완성됩니다. 기존 설정을 읽고 최소 변경만 적용합니다.