비개발자도 OK — 핵심 3단계

내가 만든 HTML 결과물을
인터넷으로 직접 알리고 싶다면!
브라우저에서 클릭 몇 번으로 OK!

잘 다듬어진 HTML 파일이 있다고요?!
GitHub에서 저장소(Repository) 만들고 → 파일 올리고 → URL로 공유할 수 있어요!

읽기 시간: 5분 브라우저만 필요 한국어
Markdown의 한계 → HTML의 시각적 힘 → 공유의 번거로움 → GitHub Pages로 간단히 해결 — 4컷 인포그래픽

마크다운만으로는 부족하고, HTML은 시각적으로 강력하지만 공유가 번거롭죠 — GitHub Pages 한 번이면 URL 하나로 끝.

한 눈에 보는 흐름

내 HTML 파일
index.html
GitHub 저장소
main / docs/
GitHub Pages
*.github.io
동료 · 고객
공개 저장소 무료

별도 서버·비용 없음

HTTPS 기본

인증서 자동 발급·갱신

1~2분이면 배포

저장 즉시 전 세계 공개

1

저장소 만들고 Pages 켜기

GitHub에 로그인한 뒤, 브라우저에서 아래 순서로 클릭만 하면 끝입니다. GitHub 계정이 없다면 먼저 무료 가입하세요.

  1. 우측 상단 ＋ → New repository
  2. 저장소 이름 입력 (예: home), Public 선택, Add a README 체크, Create repository
  3. 저장소 화면에서 Settings → Pages 이동
  4. Source: Deploy from a branch → Branch는 main, 폴더는 /(root) 또는 /docs 선택 후 Save (실습은 /docs로 안내)
완료 확인 Settings → Pages 상단에 "Your site is live at …" 메시지가 뜨면 성공. URL은 https://<계정>.github.io/<저장소>/ 형식입니다.
폴더는 /docs 추천 웹사이트 파일과 다른 자료를 분리할 수 있어 관리가 편합니다. Jekyll 같은 Markdown을 정적 웹 소스코드로 빌드하는 도구를 쓰지 않을 거라면, 해당 폴더에 .nojekyll이라는 빈 파일을 하나 두면 안전합니다.
실제 작업 화면
2

HTML 파일 직접 작성하고 배포 확인

저장소에서 바로 HTML 파일을 만들어 Pages가 정상 동작하는지 확인합니다.

  1. 저장소 Code 탭에서 Add file → Create new file 클릭
  2. 파일 경로에 docs/index.html 입력 후 간단한 HTML 코드 작성
  3. 하단 Commit changes 버튼 클릭
  4. Settings → Pages에서 "Your site is live" 메시지 확인 → Visit site
  5. 브라우저에서 배포된 페이지가 정상 출력되는지 확인
파일 이름은 index.html 폴더에 접근하면 자동으로 index.html이 열립니다. Step 1에서 Pages Source를 /docs로 설정했다면, 파일 경로도 docs/index.html로 만들어야 합니다.
배포 반영에 시간이 걸립니다 파일을 만들거나 업로드한 뒤 실제 사이트에 반영되기까지 수 초~수십 초가 소요됩니다. 커밋 직후 페이지가 안 보이면 잠시 기다린 뒤 새로고침하세요.
실제 작업 화면
3

기존 HTML 파일 업로드하고 결과 공유

이미 완성된 HTML 파일이 있다면, 드래그 & 드롭으로 저장소에 올리고 바로 공유할 수 있습니다.

  1. docs/ 폴더로 이동 → Add file → Upload files 클릭
  2. HTML 파일과 필요한 리소스를 화면으로 드래그 & 드롭
  3. 커밋 메시지 입력 후 Commit changes 클릭
  4. 1~2분 후 배포된 URL로 접속해 결과 확인
  • 잘 보이면 그 링크를 Teams · Outlook · 카카오톡 등에 그대로 붙여 공유하면 끝.
  • 수정이 필요할 땐 저장소에서 파일을 열어 연필 아이콘으로 편집 후 Commit — 즉시 반영됩니다.
배포 반영에 시간이 걸립니다 파일을 업로드한 뒤 실제 사이트에 반영되기까지 수 초~수십 초가 소요됩니다. 커밋 직후 페이지가 안 보이면 잠시 기다린 뒤 새로고침하세요.
안 보일 때 체크 3가지
  • Pages Source 폴더 설정이 실제 업로드한 폴더와 같은가
  • 파일 이름이 index.html인가 (대소문자 주의)
  • 배포 완료 전일 수 있음 — 1~2분 기다린 뒤 새로고침
실제 작업 화면
직접 확인해 보세요 위 가이드로 실제 배포된 테스트 사이트를 방문해 볼 수 있습니다: 해당 소스 코드는 https://github.com/studydev/home repository에서 참고할 수 있습니다.

실습으로 더 깊이 익히기

GitHub Pages의 기본 개념을 먼저 이해하고, 실습으로 직접 따라해 보세요. 이론 → 실습 순서로 진행하면 더 효과적입니다.

이론 GitHub Pages 기본 이론

Pages의 동작 원리·구조·핵심 개념을 빠르게 파악하는 이론 문서
실습 GitHub Pages 핸즈온 (한국어)

내 저장소에서 단계별 이슈를 따라가며 직접 배포해 보는 공식 실습
추천 학습 순서
  1. 먼저 이론 문서로 Pages의 동작 방식과 개념을 파악
  2. 이어서 핸즈온 실습으로 내 저장소에 직접 배포하며 체험

고급 · 개발자용 (선택)

필요한 경우에만 펼쳐 보세요. 기본 공유에는 필요 없습니다.

  1. 도메인 등록업체의 DNS 관리에서 CNAME 레코드 추가 — Host: docs, Value: <계정>.github.io
  2. 저장소 Settings → Pages → Custom domain에 docs.example.com 입력 → Save
  3. DNS 체크가 녹색이 되면 Enforce HTTPS 체크
참고: 이 사이트도 GitHub Pages입니다! 지금 보고 계신 ms.studydev.com 역시 GitHub Pages 위에서 커스텀 도메인을 연결하여 운영 중입니다. 아래는 실제 설정 화면입니다.
ms.studydev.com 커스텀 도메인 설정 — GitHub Pages Settings 화면

루트 도메인(example.com)을 연결하려면 A/ALIAS/ANAME 레코드가 필요합니다. 최신 IP와 자세한 내용은 GitHub 공식 문서를 참고하세요.

터미널
$ git clone https://github.com/<계정>/<저장소>.git $ cd <저장소> && cp ~/report.html docs/index.html $ git add . && git commit -m "publish" && git push

push 즉시 자동 빌드·배포가 실행됩니다.

HTML 파일이 하나일 땐 괜찮지만, 문서가 10개, 20개로 늘어나면 "어떤 문서가 있는지" 목록을 직접 관리하기 어렵습니다. 이럴 때 GitHub Actions를 사용하면, HTML이 추가될 때마다 자동으로 네비게이션용 메타 파일을 생성하고, 랜딩 페이지에서 문서 목록을 동적으로 렌더링할 수 있습니다.

동작 원리
HTML 문서
추가 · 수정
git push
(main 브랜치)
GitHub Actions
트리거
manifest.json
자동 생성
manifest.json
랜딩 페이지
fetch & 렌더
문서 카드
자동 목록
실제 구현 예시 — ms.studydev.com

지금 보고 계신 ms.studydev.com이 바로 이 방식으로 운영됩니다. 아래는 실제 저장소 구조입니다.

📁 studydev/ms ├── 📁 .github/workflows │ └── 📄 generate-manifest.yml ← Actions 워크플로 ├── 📁 scripts │ └── 📄 generate_manifest.py ← docs/ 스캔 → manifest 생성 └── 📁 docs ← GitHub Pages 루트 ├── 📄 manifest.json ← 자동 생성되는 메타 파일 ├── 📄 index.html ← 메인 랜딩 (카드 목록) ├── 📁 azure │ ├── 📄 index.html ← 카테고리 랜딩 (manifest fetch) │ ├── 📁 hosted_agent/ │ └── 📁 llm_model_migration/ ├── 📁 m365 │ └── 📁 cowork_html_guide/ … └── 📁 github └── 📁 pages_publishing/ …
핵심 코드 흐름
  1. Python 스크립트가 docs/ 아래 각 카테고리 폴더를 스캔하여, <title>과 설명을 추출합니다.
  2. 결과를 docs/manifest.json에 JSON 형태로 저장합니다.
  3. 각 카테고리 랜딩 페이지(azure/index.html 등)가 manifest.json을 fetch해서 문서 카드 목록을 자동 렌더링합니다.
manifest.json (자동 생성 예시)
{ "categories": { "github": { "label": "GitHub", "docs": [ { "slug": "pages_publishing", "title": "내가 만든 HTML 결과물을 공유하고 싶다면!", "path": "github/pages_publishing/" } ] } } }
직접 참고하기

꼭 알아둘 제한 사항

GitHub Pages는 비상업적 · 정적 용도의 무료 서비스입니다. 자세한 내용은 GitHub Pages 제한 문서에서 확인하세요.

항목기준
저장소 / 게시 사이트 크기각 1 GB 권장
월 대역폭100 GB (soft)
빌드 횟수시간당 10회 (custom Actions 사용 시 미적용)
배포 타임아웃10분 초과 시 자동 중단
상업 · 전자상거래 · SaaS 용도사용 금지
참고 GitHub Free 플랜은 공개 저장소에서만 Pages를 무료로 제공합니다. 비공개(Private) 저장소에 쓰려면 Pro/Team/Enterprise 플랜이 필요합니다. 또한 동적 백엔드(DB·API 서버)는 지원하지 않습니다.

참고 자료

GitHub Pages 기본 이론

Pages 동작 원리·구조·핵심 개념 파악
skills-kr/github-pages (실습)

단계별 이슈를 따라가는 공식 한국어 핸즈온 코스
GitHub Pages 사이트 만들기 (공식)

저장소 생성 · 퍼블리싱 소스 설정
GitHub Pages 제한 (공식)

사용 한도 · 금지된 용도
M365 Copilot Cowork로 HTML 만들기

여기서 만든 결과물을 본 가이드로 공유