feat: 인터랙티브 랜딩 페이지로 사이트 개편 (정적 프리렌더 + GitHub Pages)

[SimYunSup]

무엇을 바꿨나요

식탁보를 소개하는 랜딩 페이지를 새로 만들고, 홈페이지를 그 사이트로 교체합니다. 지금은 Bootstrap + marked.js로 docs/index.html 한 장에서 해시 라우팅(#install, #faq)으로 문서를 그리고 있는데, 이를 React + TanStack Start 사이트로 바꾸고 빌드할 때 라우트마다 HTML을 미리 만들어 배포합니다.

바뀌어도 그대로인 것부터 적습니다.

• 서버는 여전히 없습니다. 결과물은 정적 파일 디렉터리 하나(dist/client)이고 GitHub Pages가 그대로 서빙합니다.
• 문서 내용은 한 글자도 바뀌지 않았습니다. docs/docs/*.md → src/content/docs/*.md 이동만 했고 git도 rename으로 인식합니다.
• 커스텀 도메인·이미지·후원자 JSON 주소가 모두 유지됩니다. CNAME, .nojekyll, sponsors.json, docs/images/*를 public/으로 옮겼고, public/ 아래는 빌드 결과 루트로 그대로 복사됩니다. 즉 https://yourtablecloth.app/docs/images/Step1.png, /sponsors.json 주소가 그대로입니다.
• 주간 후원자·기여자 갱신 워크플로도 그대로 돕니다. 쓰는 위치만 docs/ → public/으로 바뀌었습니다.
• Pages 설정은 지금과 같습니다. 배포 소스가 이미 GitHub Actions라서 저장소 설정을 건드릴 필요가 없습니다.

새로 하는 일은 이렇습니다.

• 스크롤에 따라 식탁보가 상 위에서 걷히고 그 아래 보안 프로그램들이 드러나는 3D 히어로(three.js), 카탈로그 수치를 근거로 한 랜딩 섹션들, 한국어/영어 전환, 다크·라이트 테마
• 문서 주소가 /#faq에서 /docs/faq로 바뀝니다. 페이지마다 실제 HTML 파일이 있으므로 검색엔진과 SNS 카드가 문서별 제목·설명을 그대로 읽습니다.
• 예전 해시 주소는 홈에서 받아 새 경로로 넘깁니다(src/lib/legacy-hash.ts). /#install, /#faq, /#privacy 같은 기존 링크가 죽지 않습니다.
• 파일이 없는 주소는 404.html이 404 상태로 응답한 뒤 앱이 이어받아 404 화면을 그립니다.

후원자 목록

기존 워크플로가 만들던 sponsors.json을 사이트가 실제로 읽어서 그리도록 연결했습니다.

• 워크플로가 public/sponsors.json을 쓰고 → 빌드가 그 파일을 읽어 → 홈의 후원자 영역과 /docs/sponsor 페이지에 같은 목록을 그립니다(src/data/sponsors.ts).
• 목록은 HTML에 박혀 나가므로 브라우저가 따로 받아오는 요청이 없고, 토큰도 브라우저에 닿지 않습니다. 비공개를 선택한 후원자는 이름 없이 인원수(+1)로만 표시합니다.
• 커밋된 public/sponsors.json은 빈 placeholder 대신 현재 배포본으로 교체했습니다. API 호출이 실패하면 기존 로직대로 마지막 배포본을 가져오고, 그마저 실패해도 커밋본이 남아 목록이 0명으로 덮이지 않습니다.
• JamesIves/github-sponsors-readme-action 스텝은 뺐습니다. 이 액션은 sponsor.md의 <!-- sponsors --> 사이에 HTML을 넣는데, 이제 같은 자리를 위 데이터로 직접 그리기 때문에 두 벌이 됩니다. 마커는 그대로 두었으니 되돌리기도 쉽습니다.

배포 방식

.github/workflows/deploy.yml의 앞부분(후원자·기여자 목록 생성)은 그대로 두고 뒤에 빌드 단계를 넣었습니다.

1. 후원자·기여자 목록을 public/sponsors.json, public/contributors.json에 생성 (기존 로직 그대로, 경로만 변경)
2. pnpm install --frozen-lockfile → pnpm build
3. dist/client를 Pages 아티팩트로 업로드

확인한 것

• pnpm build → HTML 10개 생성 (/, /docs, 문서 7개, 404.html)
• 빌드 결과를 GitHub Pages와 같은 규칙(디렉터리 → index.html, 없으면 404 상태로 404.html)으로 서빙해 전 페이지 확인: 4xx 요청 0건, 콘솔 에러 0건
• 문서 스크린샷 4장 정상 로드, /#faq → /docs/faq 리다이렉트 동작, 언어 전환 동작, 후원자 아바타 3명 + 익명 1명 표시
• pnpm exec tsc --noEmit 통과, 소스맵은 배포물에 포함되지 않음

검토를 부탁드리고 싶은 부분

1. /docs/*.md 원문 주소: 예전 사이트가 런타임에 가져다 쓰던 https://yourtablecloth.app/docs/faq.md 같은 주소는 더 이상 응답하지 않습니다(문서 페이지 자체는 /docs/faq로 정상 제공). 이 주소를 참조하는 곳이 있으면 알려 주시면 함께 내보내겠습니다.
2. 문구와 수치: 랜딩 문구는 기존 문서와 카탈로그를 근거로 썼고, 수치는 src/data/catalog.ts·src/data/community.ts에 읽은 날짜(asOf)와 함께 두었습니다. 사실관계나 표현이 프로젝트 의도와 다르면 고치겠습니다.
3. 로고: public/tablecloth.svg는 프로젝트 로고를 수정 없이 사용했고, 출처는 푸터에 적어 두었습니다.

로컬에서 확인하시려면 pnpm install && pnpm build && pnpm preview 후 http://localhost:3100을 열어 보시면 됩니다.