Stacy 是一個網站產生器,它將 Contentful CMS 的內容與 Handlebars 模板結合來建立網站頁面。
Stacy 將 Contentful 的條目內容類型與網站專案中的 Handlebars 範本以一對一的關係配對 — 您的Content model中定義的每個條目類型都有一個範本。從 Stacy 的角度來看,條目有兩種類型:頁面條目和模組條目。頁面條目與其範本結合,會在唯一的 URL 處產生單一網站頁面。模組條目可以包含在頁面和其他模組中,使用 Contentful 的引用欄位來建立可重複使用的內容片段,或者只是透過將其分解為更小的片段來提供內容和模板結構。
Stacy 與許多現有靜態網站產生器的不同之處在於,它支援將網站自動發佈到 Amazon Cloud 中的 S3 儲存桶,因此可以在網際網路上提供服務。 Stacy 在 Amazon Cloud 中部署了特殊的基礎設施,可以透過其 Webhooks 功能連接到 Contentful。當您的 Contentful 空間中的內容更新時,Stacy 在 Amazon Cloud 中部署的網站基礎架構會收到通知,並僅自動重新產生和重新發佈網站中受更新影響的頁面。無需手動重新生成網站並重新部署。
使用 Stacy 時,您的網站是一個 NPM 項目,通常在 git 儲存庫中檢查以進行版本控制。此項目包括您的 Handlebars 範本和靜態內容(例如 CSS 樣式表、網站設計中使用的圖像、字體等),而網站內容則位於 Contentful 空間中。在網站專案中,網站開發人員使用 Stacy 命令列工具來開發、發布和重新發佈網站。一旦網站在 Amazon Cloud 中發布,內容作者就只能使用 Contentful UI。
有關詳細的教學/演練,請參閱使用 Stacy 建立網站。
首先,您需要一個內容豐富的空間來儲存您的網站內容。一旦完成,您就可以為您的網站建立一個新專案。
確保您已將 Node.js 版本 10.16.3 或更高版本與 npm 一起安裝。如果您要在 Amazon Cloud 中發佈網站,您還需要安裝 AWS CLI。
首先在全域安裝 Stacy:
npm install -g stacy
在您的 Contentful 空間中,前往空間設定→API 金鑰,然後在內容交付/預覽令牌中新增 API 金鑰。注意空間 ID和Content Delivery API 存取權杖值,您將使用它們將 Stacy 環境連接到 Contentful 空間。
現在,您可以為您的網站產生初始項目:
stacy new --cf-space <your space ID> --cf-access-token <your access token> mywebsite
這將在目前目錄中建立一個名為“mywebsite”的新專案目錄。 “mywebsite”值稱為網站 ID 。使用不同的值來標識您的網站。該值應該是 URL 友善的(小寫字母、數字和破折號)。
在您的專案目錄中,將靜態內容放在/static
下(這會按原樣複製到您的網站),並將條目模板放在/templates
下。範本檔案的名稱(不含副檔名)必須與內容內容模型中對應的條目內容類型完全相符。在/templates
下,模板檔案可以組織在子資料夾中。但是,檔案名稱在所有子資料夾中必須是唯一的,因為它們用於唯一地將範本與條目內容類型相符( /templates
中的子資料夾不起作用)。
注意:通常,模板與條目內容結合會產生 HTML。如果您需要產生其他類型的內容,可以為範本名稱新增副檔名。例如, page.hbs
產生 HTML。若要產生純文本,請使用page.txt.hbs
。這也意味著page.hbs
和page.html.hbs
是相同的。
現在您可以在本地運行您的網站以進行開發:
stacy serve
您可以在http://localhost:8080/
上查看您的網站。編輯任何範本、靜態內容或 Contentful 中的內容後,只需重新載入頁面即可。
若要停止 Stacy 本機網路伺服器,請使用Ctrl+C
。
執行stacy --help
查看其他可用指令。
您可以將專案目錄的內容簽入 git 儲存庫,例如 GitHub 或 Bitbucket。
在範本內部,所有輸入欄位都可以透過內容模型中定義的欄位 ID來使用。您可以直接在模板中引用它們。例如:
這將輸出條目caption
欄位的值。請注意,此處使用的是欄位 ID ,而不是欄位名稱。
Stacy 增加了一些可以在模板中使用的特殊幫助器:
module <reference field>
- 包含引用類型欄位引用的模組條目。例如,假設您有一個包含 ID paragraphs
字段,並且它是一個引用列表:
asset <asset field>
- 包含引用的資產,例如圖像。例如:
目前,僅支援圖像資源,並為其呈現 HTML <img>
標籤。
assetSrc <asset field>
- 取得資產的 URL。例如:
assetTitle <asset field>
- 取得資產的標題。例如:
markdown <long text field>
- 渲染 Markdown 長文字欄位。例如:
請注意此處需要三重花括號,因為幫助程式產生不需要轉義的 HTML。
richText <rich text field>
- 渲染富文本欄位。例如:
與markdown
一樣,請注意三大括號。
json <field>
- 輸出欄位的內部內容 JSON 表示形式。例如:
該助手對於診斷問題可能很有用。
如上所述,您在內容空間的內容模型和範本中定義的內容類型之間存在一對一的關係。
注意:嚴格來說,對於給定的內容類型,您可以有多個模板,以便為相同內容條目產生不同類型的檔案。例如,對於內容類型 ID module
您可以使用模板module.html.hbs
和module.xml.hbs
。第一個範本將為條目產生一個 HTML 文件,第二個範本將產生一個 XML 文件。
定義內容類型時,請記下Api 識別碼(也稱為內容類型 ID )。內容類型的範本檔案必須具有相同的名稱(加上副檔名)。
頁面條目(與模組條目相反)的內容類型有一個要求:頁面內容類型必須定義必需的slug欄位。當內容條目與對應的範本組合時,該欄位中的值將決定產生的文件的名稱。例如,如果頁面條目的 slug 值為“index”,則產生的頁面將為“/index.html”。如果 slug 是“more/terms”,則頁面將為“/more/terms.html”。等等。
預設情況下,slug 欄位的欄位 ID 必須為slug
。可以在專案的stacy.json
檔案中覆寫該 ID。除了在內容類型定義中將 slug 欄位設定為必要之外,還建議將自訂匹配模式驗證器與其關聯,以確保欄位值的特定格式。驗證器的正規表示式可以是^w[w-]*(/w[w-]*)*$
。
當您準備好在 AWS 中部署網站時,首先需要在您的 AWS 帳戶下設定 Stacy 基礎架構。您必須先執行幾個步驟才能執行此操作:
建立目標 S3 儲存桶。這是您的網站發布和服務的地方(可能透過 CloudFront)。或者,您可以使用現有的儲存桶(Stacy 也支援在目標儲存桶的子資料夾中發布)。
如果您還沒有,請建立一個 S3 儲存桶,Stacy 將使用該儲存桶來上傳發布者 Lambda 函數包。發布者 Lambda 函數是回應 Contentful發布和取消發布事件並更新目標 S3 儲存桶中的相關頁面和資產的部分。
建立發布者包:
stacy build-publisher
這將在您的專案中的/build/stacy-mywebsite-publisher.zip
下建立發布者 Lambda 函數包。將此檔案上傳到您的 Lambda 函數 S3 儲存桶。
Stacy 的stacy new
指令已為 AWS 環境產生 CloudFormation 模板,並將其儲存在專案中的/misc/cfn-template.json
下。如有必要,您可以查看並自訂它。否則,請繼續在您的 AWS 帳戶下為您的網站建立 Stacy 堆疊。
建立 CloudFormation 堆疊後,您需要調整目標 S3 儲存桶的策略,以允許 Stacy 發布者在其中發布產生的網站內容。儲存桶的策略可以包括以下內容:
{
"Version" : " 2012-10-17 " ,
"Statement" : [
{
"Effect" : " Allow " ,
"Principal" : {
"AWS" : " <Stacy publisher role ARN> "
},
"Action" : [
" s3:PutObject " ,
" s3:DeleteObject "
],
"Resource" : " arn:aws:s3:::<bucket name>/* "
}
]
}
在上述策略中,將 Stacy 發布者角色 ARN 替換為您可以在 CloudFormation 堆疊的PublisherRoleArn
輸出參數中找到的值,並將儲存桶名稱替換為目標網站儲存桶名稱(應用策略的儲存桶)。
現在您必須準備好用於發布的開發環境。開啟並編輯網站專案中的.env
檔。在其中,將所有AWS_*
變數設定為正確的值。請注意,您可以在 CloudFormation 堆疊的PublishEventSourceMappingId
輸出參數中找到AWS_PUBLISH_EVENT_SOURCE_MAPPING
變數的值。
正確設定.env
檔案後,您可以使用以下方式發佈您的網站:
stacy publish
最後一個設定步驟是在您的 Contentful 空間中設定一個 Webhook,以便在發布和取消發布事件時呼叫 Stacy 發布者。在您的 AWS 帳戶中,在 API Gateway 服務中找到 Stacy 為您建立的 API。 API 的prod
階段只有一種方法POST /publish
。請注意其調用 URL 。
另外,請前往API 金鑰部分並記下為 Stacy 建立的 API 金鑰的值。
在您的 Contentful 空間中,前往空間設定→Webhooks並新增 Webhook。將 API Gatwey 的呼叫 URL 放入 URL 欄位中(保留方法POST
)。然後選擇“觸發器”部分中的“選擇特定觸發事件”選項。選取條目和資產行中的發布和取消發布核取方塊(總共選取 4 個核取方塊)。
在標頭部分中點選新增秘密標頭。將「X-API-Key」放入「金鑰」字段,並在「值」欄位中放入來自 API 閘道的 API 金鑰。
儲存此 Webhook 後,在 Contentful 中發布和取消發布條目和資產將觸發 AWS 設定中的發布者,一切都已準備就緒!