SiteKit 是做什麼的?
SiteKit 是一個以 AI 為優先的 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、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 可發現性(標準網址、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檢查多語言網站的翻譯完整性(單語言網站可順利通過)。在 build/serve 上使用--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。