SiteKit 是做什么的?
SiteKit 是一个 AI 优先的 Swift 静态网站生成器,围绕阶段化流水线构建:发现 → 加载 → 丰富 → 页面渲染 → 系统渲染 → 输出处理,外加独立于内容的资源遥传。每个阶段对应一个 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、Cookie) | references/legal-pages.md |
DocC / Markdown 指令扩展(@Metadata、@Row、@TabNavigator、@Video、@Image、@Links等)+ 优雅降级约定 | references/markdown-extensions.md |
| 多语言站点(翻译、区域后缀、验证) | references/localization.md |
| 无障碍审计(WCAG AA 对比度、替代文本、键盘导航) | references/accessibility.md |
| SEO + ASO + AI 可发现性(规范 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 变体,询问设置模式,并在路由到一种 CI + 一种托管文件之前遍历 CLI 认证。对于全新部署,请从这里开始。如果已经知道目标(例如重新配置现有部署),可以直接跳转:
| 如果用户询问…… | 则阅读…… |
|---|---|
| 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– 不可变、流畅的构建器。每个配置方法(.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检查多语言站点的翻译完整性(单语言站点平凡通过)。--base-url <url>在构建/服务时覆盖SiteConfig.baseURL(用于暂存部署)。
风格说明
当通过此技能生成站点内容时,保持真实的独立开发者声音。短段落。使用人称代词。避免企业修辞。完整的作者声音指南和学习循环说明位于 references/content-writing.md。
流水线概览
| 阶段 | 协议 | 扩展位置 |
|---|---|---|
| 0. 资源遥传(独立于内容) | Teleporter | .teleporter(_:) |
| 1. 发现 | ContentDiscovery | .contentDiscovery(_:) |
| 2. 加载 | Loader<Source, Output> | .articleLoader(_:), .staticPageLoader(_:) |
| 3. 丰富 | 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。