Static site → GitHub Pages
전체 워크플로: 데이터 → 독립형 HTML/CSS/JS 페이지 → 브라우저 검증 → GitHub Pages 게시.
대상: 1개에서 수백 개 항목, 단일 작성자, 실행 시 의존성 제로.
사용 시기
| 사용 가능 | 사용 불가 |
|---|---|
| "이 리스트/표로 페이지 만들어 줘", 갤러리, 데이터 대시보드 | 백엔드, 인증, 데이터베이스가 필요한 앱 → 먼저 요청 |
| "GitHub / GitHub Pages에 게시해 줘" | 프레임워크(Next, Astro, Hugo)로 생성된 사이트 → 해당 프레임워크 워크플로 사용 |
| 기존 페이지를 데이터(제목, 날짜, 가격 등)로 재현 | 타사 사이트의 디자인/CSS/HTML 복사 → 거절하고 깔끔한 디자인으로 재작성 |
절대 규칙
- 직접 디자인. 타사 사이트의 CSS, HTML 또는 애셋을 절대 복사하지 마세요. 정보 구조에서 영감을 얻는 것은 괜찮지만, 디자인 시스템을 그대로 가져오는 것은 안 됩니다.
- 사실은 가능, 저작물은 불가. 제목, 날짜, 가격, 평점, 링크 = 사실적 데이터, 재사용 가능. 편집 텍스트, 설명, 시각 자료 = 보호됨: 복사하지 마세요. 이미지의 경우, 커밋 대신 원본 CDN에 핫링크하세요 (
reference/data-and-ethics.md참고). - 접근 보호 준수. 크롤러를 차단하는
robots.txt, Cloudflare 챌린지/봇 → 우회하지 마세요. 공식 API, 키를 찾거나, 간단한 외부 링크로 대체하세요. - 실제 브라우저에서 항상 확인하세요 (스크린샷 + 클릭 테스트) "완료"라고 말하기 전에.
- 저장소 이름/계정이 모호할 경우 확인 없이 게시하지 마세요.
- 확인 없이 사용자 정의 도메인을 생성하지 마세요. 사용자가 지정하지 않았다면 Cloudflare 리디렉션을 원하는지, 어떤 도메인인지 질문하세요 (6단계). 서브도메인을 임의로 만들거나 생성하지 마세요: DNS는 외부에 보이는 부작용입니다.
워크플로
1. 범위 설정 (30초)
-
어떤 데이터, 항목 수, 단일 갱신 또는 반복 갱신?
-
예상 출력: 한 페이지? 정렬/검색? 어떤 비즈니스 표시 규칙?
-
게시 위치: GitHub 계정, 저장소 이름, 공개/비공개 (Pages는 무료 계정에서 공개 저장소 필요).
-
사용자 정의 도메인 — 명시되지 않은 경우 명시적으로 질문. 한 번에 질문하고 기본 제안을 제시하세요:
Cloudflare 리디렉션을
<owner>.github.io(CNAME, 프록시 비활성화)로 설정할까요? 그렇다면 어떤 서브도메인/경로를 사용할까요?이름은 스킬 측면에서 자유롭지만, 도메인은 생성 즉시 공개됩니다: 명시적인 답변 없이 아무것도 만들지 마세요. 사용자가 '아니요'라고 답하면
https://<owner>.github.io/<repo>/URL에서 멈추고 DNS 항목을 만들지 마세요.
2. 데이터 가져오기
단일 스크립트 실행 → data.json = 진실 공급원, 렌더링과 분리.
python3 fetch_data.py # → data.json
예의: 요청 간 0.3–0.7초, 명시적 User-Agent, 429/5xx 재시도.
세부 사항 및 까다로운 경우(PoW Anubis, Cloudflare, 퍼지 매칭, 키 없는 API): reference/data-and-ethics.md 참고.
3. 페이지 생성
템플릿에서 시작, 백지에서 시작하지 마세요:
cp .dsh/skills/static-site-publish/templates/{index.html,styles.css,script.js} ./site/
cp .dsh/skills/static-site-publish/templates/build.py ./site/ # data.json → index.html
python3 ./site/build.py
build.py: 작은 Python 생성기 (f-string +html.escape)로 데이터를 카드 그리드에 주입합니다. 데이터에 JS 런타임이 필요하지 않습니다.styles.css: 기본 어두운 테마,auto-fill minmax()그리드, CSS 변수.script.js: 열 때 즉시 검색 + 정렬 + 계산된 표시 규칙 (페이지를 다시 빌드하지 않고 유지).- 표시 시 계산 가능한 것(상태, 상대 날짜)은 JS에서 처리해야 합니다: 사이트를 매일 다시 빌드할 필요가 없습니다.
- HTML은 JS 없이도 읽을 수 있어야 하며, JS는 점진적으로 적용되어야 합니다.
4. 확인
.dsh/skills/static-site-publish/scripts/verify-site.sh ./site/index.html
Chrome 헤드리스에서 페이지를 열고 /tmp/site-shot.png를 작성한 후 클릭 오버레이 테스트를 실행합니다. 결론을 내리기 전에 스크린샷을 보세요 (read_image 도구).
체크리스트: 데스크탑 + 모바일 렌더링, 데이터 완전성(항목 수 세기), 링크 정확성, 겹침 없음.
5. 게시
.dsh/skills/static-site-publish/scripts/publish-gh-pages.sh ./site my-repo-name
스크립트: gh auth status → git init/commit → gh repo create --source --push → gh api POST /pages → URL이 200을 반환할 때까지 폴링 → 최종 URL 표시.
Pages 지연 시간은 20~90초입니다: 200이 반환될 때까지 "작동하지 않는다"고 결론 내리지 마세요. 또한 gh api repos/{owner}/{repo}/pages/builds/latest --jq .status = built를 확인하세요.
6. 사용자 정의 도메인 + Cloudflare
사용자가 요청한 경우에만 (1단계 참조). DNS는 공개적입니다: 막연한 "예"를 AI가 선택한 도메인 이름으로 재해석하지 마세요.
필수 순서: DNS 먼저, 인증서 다음, Enforce HTTPS 마지막. 시작하기 전에 사이트가 *.github.io에서 이미 200을 반환해야 합니다.
a. Cloudflare DNS 리디렉션 (Cloudflare MCP)
토큰 전제 조건: zone.read + dns.write 범위 (Zone Read / DNS Edit). 누락된 경우 중단하고 확장을 요청하세요 — 우회하지 마세요.
GET /zones?name=<루트 도메인>→zone.id. 영역이 0개인 경우: 이 계정에 도메인이 없으므로 요청.GET /zones/{zone_id}/dns_records?name=<fqdn>→ 동일한 CNAME이 이미 존재하면 아무것도 다시 생성하지 마세요 (멱등성).POST /zones/{zone_id}/dns_records:
{ "type": "CNAME", "name": "<서브도메인>", "content": "<owner>.github.io",
"proxied": false, "ttl": 1 }
proxied: false= DNS only, 협상 불가: Cloudflare 프록시는 GitHub가 인증서를 발급하지 못하게 합니다.- 대상은
<owner>.github.io이며, 끝에 슬래시 없고 저장소 이름 없음 (jamesdadams.github.io,.../my-repo아님). ttl: 1= 자동.
- API뿐만 아니라 공개 DNS로 확인:
dig +short <fqdn> CNAME @1.1.1.1 # → <owner>.github.io.
dig +short <fqdn> A @1.1.1.1 # → 185.199.108-111 .153
b. GitHub Pages 측 도메인 + Enforce HTTPS
.dsh/skills/static-site-publish/scripts/set-pages-domain.sh <owner>/<repo> <domaine> ./site
스크립트: 사이트에 CNAME 파일을 씁니다(재배포 시 유지되고 도메인 손실 방지) → PUT /repos/{owner}/{repo}/pages with cname → https_certificate.state = approved를 기다립니다 → https_enforced: true를 활성화합니다.
⚠️ https_enforced: true는 인증서가 존재할 때까지 400을 반환합니다. 실제 지연 시간: CNAME 생성 후 5~20분. 이것이 스크립트가 실패하지 않고 반복하는 이유입니다. 인증서 발급 전에 수동으로 "Enforce HTTPS"를 체크하지 말고, 이 기간 동안 실패로 결론 내리지 마세요.
c. 최종 확인
curl -sI https://<domaine>/ | head -5 # 200 + header server: GitHub.com
그런 다음 브라우저에서 페이지를 다시 열어 (4단계) 사용자 정의 URL에서: 200은 상대 경로(styles.css, script.js)가 올바르게 해석된다는 것을 증명하지 않습니다 — 도메인 루트에서 서비스되는 프로젝트 페이지의 전형적인 함정입니다.
7. 업데이트 가능하게 만들기
- git 디렉토리를 사용자의 프로젝트 디렉토리에 두세요 (/tmp는 재부팅 시 지워짐).
README.md에 문서화: 데이터 출처, 추출 재실행 방법, 고정된 것(데이터)과 동적인 것(JS 계산 규칙).- 자동으로 업데이트되지 않는 것을 사용자에게 명시적으로 알리세요.
이미 겪은 함정
| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 403 "잠시만 기다려 주세요…" | Cloudflare 챌린지 | 한계 문서화, 공식 API 또는 외부 링크; 우회 시도 금지 |
| 잘린 페이지 "봇이 아님을 확인 중입니다" | PoW Anubis | 챌린지 해결 (참고 자료 참조) 또는 사용자에게 내보내기 요청 |
| 모든 항목에서 0 결과 반환하는 선택기 | 잘못된 패턴 (예: /games/lib/genre: vs /games/lib/popular/genre:) | HTML 샘플을 출력하고 반복 전에 1페이지에서 정규식 테스트 |
| 카드 클릭 시 올바른 링크 열리지 않음 | <a> 레이어가 위치 지정된 하위 요소에 가려짐 | 장식 요소에 pointer-events: none; elementFromPoint로 테스트 |
| GitHub Pages 처음 몇 분 동안 404 | 빌드 진행 중 | 최대 90초 폴링 |
| 한 열의 데이터 비어 있음 | 소스 측 변수 레이블 ("Released" vs "Early Access") | 관대한 패턴 + 항목별 로그, 절대 조용한 except: pass 없음 |
https_enforced 400 "인증서가 존재하지 않음" | 인증서가 아직 발급되지 않음 | https_certificate.state = approved까지 대기 (5-20분), 스크립트 반복 |
| 30분 후 사용자 정의 도메인 404 | CNAME 없음 / 잘못된 소유자 / 저장소에 CNAME 파일 없음 | dig로 CNAME 확인, set-pages-domain.sh 재실행 |
| 프록시 활성화 후 HTTPS 깨짐 | 레코드가 Proxied로 설정됨 | DNS only(proxied: false)로 되돌리기, GitHub 인증서는 프록시를 통해 검증할 수 없음 |
| "도메인이 이미 사용 중입니다" | 도메인이 계정의 다른 저장소에 이미 선언됨 | 저장소당 하나의 사용자 정의 도메인; 재할당 전에 이전 도메인 해제 |
사용자 정의 도메인에서 CSS/JS 404이지만 *.github.io/repo/에서는 정상 | 루트에서 서비스되는 프로젝트 페이지에 절대 경로(/styles.css) 사용 | 상대 경로(styles.css) |
참고 자료
reference/data-and-ethics.md— 추출, PoW Anubis, Cloudflare, 라이선스, 이미지 핫링크reference/design-and-verify.md— 최소 디자인 시스템, 브라우저 테스트, 접근성reference/publish-gh-pages.md—gh명령어, 이름 지정, 도메인, 문제 해결scripts/publish-gh-pages.sh— 게시 + Pages 활성화scripts/set-pages-domain.sh— 사용자 정의 도메인 + Enforce HTTPS (Cloudflare CNAME 이후)scripts/verify-site.shtemplates/{index.html,styles.css,script.js,build.py}