SiteKit은(는) 무엇을 하나요?
SiteKit은 AI 우선(AI-first) Swift 정적 사이트 생성기로, 단계 기반 파이프라인(Discovery → Loading → Enrichment → Page rendering → System rendering → Output processing, 그리고 콘텐츠 독립적 자산 텔레포트)을 중심으로 구축되었습니다. 각 단계는 하나의 Swift 프로토콜이며, 사이트는 SiteBuilder 팩토리 메서드(.blog(), .podcast(), .newsletter(), .portfolio(), .docs(), .docc())로 구성되고 플러그인을 교체하거나 추가하여 유연하게 커스터마이즈됩니다.
프로세스
사용자의 의도를 올바른 참조 문서로 안내합니다. 현재 작업에 필요한 참조 문서만 읽으세요.
| 사용자가 다음에 대해 묻는다면… | 다음을 읽으세요… |
|---|---|
SiteKit 설치 + 첫 사이트 스캐폴딩 (sitekit CLI) | references/bootstrap.md |
| 처음부터 새 사이트 설정 | references/onboarding.md |
| 블루프린트 선택 (Blog, Newsletter, Podcast, Portfolio, AppLanding, Snippets, IndieDev, DocC, Plain) | references/blueprints.md |
| 콘텐츠 작성 (블로그 게시물, 뉴스레터 발행물, 정적 페이지) | references/content-writing.md |
| 임프린트 / 개인정보 / 법률 페이지 (국가별, GDPR, 쿠키) | references/legal-pages.md |
DocC / Markdown 지시문 확장 (@Metadata, @Row, @TabNavigator, @Video, @Image, @Links, …) + 우아한 저하(graceful-degradation) 계약 | references/markdown-extensions.md |
| 다국어 사이트 (번역, 로케일 접미사, 검증) | references/localization.md |
| 접근성 감사 (WCAG AA 대비, 대체 텍스트, 키보드 내비게이션) | references/accessibility.md |
| SEO + ASO + AI 검색 가능성 (canonical URL, OG, JSON-LD, llms.txt) | references/seo-aso.md |
| 성능 / PageSpeed 결과 (LCP, CLS, 렌더 차단 리소스) | references/performance.md |
| 사이트 배포 (호스트 + CI 제공자 매트릭스) – 여기서 시작 | references/deployment/SKILL.md |
| 테마 커스터마이징 (프리셋, 색 구성표, 글꼴 쌍, 토큰) | references/themes.md |
새 HTML 페이지 유형을 위한 사용자 정의 Page 추가 | references/custom-pages.md |
파이프라인 확장 (Loader, Enricher, Renderer, OutputProcessor, Teleporter) | references/architecture.md |
| 빌드 / 런타임 문제 해결 | references/troubleshooting.md |
| 자체 호스팅 뉴스레터 설정 (Keila + SMTP) | references/newsletter-setup.md |
| 외부 서비스 선택 (이메일 전송, 통합) | references/external-services.md |
SiteConfig.yaml 필드 참조 | references/siteconfig-reference.md |
배포 – 공급자로 바로 이동
references/deployment/SKILL.md은 오케스트레이터입니다: Package.swift 변형을 감지하고, 설정 모드를 묻고, CLI 인증을 진행한 후 하나의 CI와 하나의 호스트 파일로 라우팅합니다. 새 배포는 여기서 시작하세요. 이미 대상을 알고 있다면(예: 기존 배포 재구성), 바로 이동하세요:
| 사용자가 다음에 대해 묻는다면… | 다음을 읽으세요… |
|---|---|
| GitHub Actions의 CI | references/deployment/ci/github-actions.md |
| GitLab CI의 CI | references/deployment/ci/gitlab-ci.md (커뮤니티; 플레이스홀더) |
| Xcode Cloud의 CI | references/deployment/ci/xcode-cloud.md (커뮤니티; 플레이스홀더) |
| Bitrise의 CI | references/deployment/ci/bitrise.md (커뮤니티; 플레이스홀더) |
| Cloudflare Pages 호스팅 | references/deployment/hosts/cloudflare-pages.md |
| GitHub Pages 호스팅 | references/deployment/hosts/github-pages.md |
| Netlify 호스팅 | references/deployment/hosts/netlify.md |
| Vercel 호스팅 | references/deployment/hosts/vercel.md |
| 지원되는 CI 제공자 / 새 CI 제공자 추가 | references/deployment/ci/README.md |
| 지원되는 호스트 / 새 호스팅 제공자 추가 | references/deployment/hosts/README.md |
직접 이동하면 오케스트레이터의 설정 모드와 Package.swift 감지를 건너뜁니다 – 이미 해결된 경우에만 이렇게 하세요.
핵심 용어 (항상 사용 가능)
- 블루프린트(Blueprint) – 사이트 유형을 위한 레시피.
SiteBuilder는 각 사이트 유형에 대한 기본 플러그인 목록을 미리 구성하는 팩토리 메서드(.blog(),.podcast(),.newsletter(),.portfolio(),.docs(),.docc())를 제공합니다.Plugin/blueprints/아래의 온디스크 블루프린트는 플러그인이 복제할 수 있는 스타터 사이트입니다. - 페이지(Page) – HTML 페이지 렌더링을 위한 사용자 대상 프로토콜.
Renderer의 하위 프로토콜입니다. 구현체는pages(in:)와renderHTML(_:context:)를 구현합니다.PageShell.wrap(content:page:context:)는 표준<head>/<header>/<footer>크롬을 자동으로 적용합니다. - 렌더러(Renderer) – 시스템 수준 출력 프로토콜.
scope: .perLocale(기본값 – 로케일당 한 번 실행) 또는.global(빌드당 정확히 한 번 실행, 사이트맵, robots, llms.txt, Cloudflare_headers에 사용)을 선언합니다. 파이프라인은scope에 따라 디스패치합니다. SiteBuilder– 불변(immutable), 유창(fluent)한 빌더. 모든 구성 메서드(.renderer,.enricher,.processor,.teleporter, …)는 새SiteBuilder를 반환합니다..run()은 CLI 동사(build,serve,validate)를 읽고 파이프라인을 실행합니다.BuildContext– 3~6단계의 모든 플러그인에 전달되는 읽기 전용 상태.config,themeConfig,sections,staticPages,tags,homeContent,router,uiStrings,outputDirectory,projectDirectory를 보유합니다.- 빌드 명령어 –
swift run Site build는 사이트를_Site/에 씁니다.swift run Site serve는 개발 서버를 실행합니다(기본:8080).swift run Site validate는 다국어 사이트의 번역 완전성을 확인합니다(단일 언어 사이트는 자동 통과).build/serve에--base-url <url>을 사용하면 해당 실행에서SiteConfig.baseURL을 재정의합니다(스테이징 배포).
스타일 참고
이 스킬을 통해 사이트 콘텐츠를 생성할 때는 정통한 인디 보이스(authentic indie voice)를 유지하세요. 짧은 문단. 개인 대명사. 기업용 에두르기(hedging)는 사용하지 마세요. 전체 저자 음성 가이드와 학습 루프 지침은 references/content-writing.md에 있습니다.
파이프라인 한눈에 보기
| 단계 | 프로토콜 | 확장 위치 |
|---|---|---|
| 0. 자산 텔레포트 (콘텐츠 독립적) | Teleporter | .teleporter(_:) |
| 1. 발견 (Discovery) | ContentDiscovery | .contentDiscovery(_:) |
| 2. 로딩 (Loading) | Loader<Source, Output> | .articleLoader(_:), .staticPageLoader(_:) |
| 3. 강화 (Enrichment) | Enricher | .enricher(_:) |
| 4. 로케일별 HTML 페이지 | Page (Renderer의 하위 프로토콜) | .renderer(_:) |
| 5. 시스템 렌더링 | Renderer + RenderScope | .renderer(_:) |
| 6. 출력 처리 | OutputProcessor | .processor(_:) |
전체 아키텍처 설명과 각 확장 지점에 대한 실제 예제는 references/architecture.md와 references/custom-pages.md를 읽으세요.
같이 보기
위의 참조 문서에서 다루지 않는 작업이 있다면 – 사이트 구축이 아닌 SiteKit의 Swift 라이브러리 자체를 수정하는 경우 – 저장소 루트에 있는 기여자 참조 문서 AGENTS.md(파이프라인 내부, 단계 프로토콜, SiteBuilder 교체 지점, 빌드 및 테스트 명령어)로 에스컬레이션하세요.
인간 대상 문서와 이 참조 문서를 모두 아우르는 작업 → 문서 인덱스는 저장소 루트의 ../../../USE-CASES.md를 참조하세요.