Community코딩 & 개발github.com

static-site-publish

Coding skill. 순수 HTML/CSS/JS로 데이터 기반의 작은 정적 사이트(리스트, 갤러리, 대시보드, 포트폴리오)를 생성하고, 헤드리스 브라우저로 검증한 후 GitHub Pages에 게시합니다. Cloudflare CNAME 리디렉션(프록시 비활성화)과 GitHub Pages의 Enforce HTTPS 설정을 지원합니다.

static-site-publish란 무엇인가요?

이 스킬은 개발자가 데이터셋(리스트, 테이블, 갤러리, 대시보드 등)을 받아서 **빌드 도구나 프레임워크 없이** 순수 HTML/CSS/JS로 정적 사이트를 만들고, 헤드리스 Chrome에서 시각적 검증(스크린샷, 클릭 테스트)을 수행한 후 GitHub Pages로 자동 배포합니다. 주요 특징은 데이터 추출 스크립트(`fetch_data.py`)로 생성한 `data.json`에서 Python 제너레이터(`build.py`)가 카드 그리드 형태의 정적 페이지를 만들고, 클라이언트 측 JS(검색, 정렬, 계산 규칙)를 추가하여 페이지를 동적으로 유지한다는 점입니다. Cloudflare MCP를 통해 사용자 정의 도메인(CNAME, DNS only)을 설정하고, GitHub Pages에서 Enforce HTTPS를 활성화하는 과정을 자동화하며, DNS와 인증서 발급 순서를 엄격히 준수합니다. Claude Code, Codex, Cursor 등 AI 에이전트와 통합되어 데이터 중심 소규모 사이트의 빠른 프로토타이핑과 게시에 적합하며, 디자인 저작권, 데이터 윤리(robots.txt, Cloudflare 챌린지 우회 금지), 사용자 확인 단계를 강제하여 안전한 배포를 보장합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JamesDAdams/my-skills/tree/HEAD/.apm/skills/static-site-publish

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Static site → GitHub Pages

전체 워크플로: 데이터 → 독립형 HTML/CSS/JS 페이지 → 브라우저 검증 → GitHub Pages 게시.

대상: 1개에서 수백 개 항목, 단일 작성자, 실행 시 의존성 제로.

사용 시기

사용 가능사용 불가
"이 리스트/표로 페이지 만들어 줘", 갤러리, 데이터 대시보드백엔드, 인증, 데이터베이스가 필요한 앱 → 먼저 요청
"GitHub / GitHub Pages에 게시해 줘"프레임워크(Next, Astro, Hugo)로 생성된 사이트 → 해당 프레임워크 워크플로 사용
기존 페이지를 데이터(제목, 날짜, 가격 등)로 재현타사 사이트의 디자인/CSS/HTML 복사 → 거절하고 깔끔한 디자인으로 재작성

절대 규칙

  1. 직접 디자인. 타사 사이트의 CSS, HTML 또는 애셋을 절대 복사하지 마세요. 정보 구조에서 영감을 얻는 것은 괜찮지만, 디자인 시스템을 그대로 가져오는 것은 안 됩니다.
  2. 사실은 가능, 저작물은 불가. 제목, 날짜, 가격, 평점, 링크 = 사실적 데이터, 재사용 가능. 편집 텍스트, 설명, 시각 자료 = 보호됨: 복사하지 마세요. 이미지의 경우, 커밋 대신 원본 CDN에 핫링크하세요 (reference/data-and-ethics.md 참고).
  3. 접근 보호 준수. 크롤러를 차단하는 robots.txt, Cloudflare 챌린지/봇 → 우회하지 마세요. 공식 API, 키를 찾거나, 간단한 외부 링크로 대체하세요.
  4. 실제 브라우저에서 항상 확인하세요 (스크린샷 + 클릭 테스트) "완료"라고 말하기 전에.
  5. 저장소 이름/계정이 모호할 경우 확인 없이 게시하지 마세요.
  6. 확인 없이 사용자 정의 도메인을 생성하지 마세요. 사용자가 지정하지 않았다면 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). 누락된 경우 중단하고 확장을 요청하세요 — 우회하지 마세요.

  1. GET /zones?name=<루트 도메인> → zone.id. 영역이 0개인 경우: 이 계정에 도메인이 없으므로 요청.
  2. GET /zones/{zone_id}/dns_records?name=<fqdn> → 동일한 CNAME이 이미 존재하면 아무것도 다시 생성하지 마세요 (멱등성).
  3. 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 = 자동.
  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분 후 사용자 정의 도메인 404CNAME 없음 / 잘못된 소유자 / 저장소에 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.sh
  • templates/{index.html,styles.css,script.js,build.py}

관련 스킬