Git · GitHub 기초집LESSON 23

GitHub Pages로 Docusaurus 사이트 배포

난이도입문 → 초급

예상 시간30분

선수지식이전 강의

23강. GitHub Pages로 Docusaurus 사이트 배포

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

로컬 빌드 결과는 다른 사람이 볼 수 없습니다. 저장소 이름에 맞는 URL 설정과 Pages 전용 Actions를 구성해 main의 검증된 사이트를 자동 게시합니다.

2. 학습 목표

3. 핵심 개념

Docusaurus는 npm run build로 build 폴더의 정적 파일만 생성합니다. GitHub Pages 배포는 Actions가 artifact를 업로드하고 Pages 환경에 게시합니다. 프로젝트 사이트 주소가 https://USER.github.io/REPO/라면 baseUrl은 /REPO/여야 합니다.

4. 단계별 명령어와 예시

파일 경로: C:\dev\git-learning-site\docusaurus.config.js

docusaurus.config.js
const config = {
  url: 'https://YOUR-NAME.github.io',
  baseUrl: '/git-learning-site/',
  organizationName: 'YOUR-NAME',
  projectName: 'git-learning-site',
  trailingSlash: false,
  onBrokenLinks: 'throw',
};

파일 경로: .github/workflows/deploy-pages.yml

.github/workflows/deploy-pages.yml
name: GitHub Pages 배포
on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v4
        with:
          path: build
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

PowerShell · 로컬 검증
npm.cmd ci
npm.cmd run build
git add docusaurus.config.js .github/workflows/deploy-pages.yml
git commit -m "ci: deploy Docusaurus site to GitHub Pages"
git push

GitHub 저장소 Settings → Pages에서 배포 원본을 GitHub Actions로 선택합니다. 메뉴는 바뀔 수 있으므로 GitHub Pages 공식 문서의 현재 절차를 확인합니다.

5. 명령어가 동작하는 이유

빌드 job은 정적 결과를 Pages artifact로 전달합니다. deploy job은 pages: write와 OIDC 검증용 id-token: write 권한으로 artifact를 github-pages 환경에 게시합니다. baseUrl이 맞아야 생성된 CSS, JS, 내부 링크가 프로젝트 경로를 가리킵니다.

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

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ