baker example page template
1.0.0
示範如何使用 Baker 建立工具建立和發布頁面。
《洛杉磯時報》使用 Baker 創建在 latimes.com/projects 上發布的靜態頁面。 《紐約時報》系統依賴一個類似此的私有版本的儲存庫。此簡化範例將暫存版本和生產版本發佈到 Amazon S3 上的公共儲存桶。
即時更新本地測試伺服器
使用 Nunjucks 製作 HTML 模板
使用 Sass 擴展 CSS
JavaScript 與 Rollup 和 Babel 捆綁
使用 quaff 導入數據
基於結構化輸入的動態頁面生成
透過 GitHub Action 在每個push事件上自動將每個分支部署到暫存環境
透過 GitHub Action 在每個release事件上將按鈕部署到生產環境
Slack 訊息透過 datadesk/notify-slack-on-build Github Action 中繼每個部署的狀態
Node.js 版本 12、14 或 16，但至少為 12.20、14.14 或 16.0。
節點包管理器
git
只需少量配置，您就可以使用此範本輕鬆發布頁面。通過一些定制，您可以使其看起來像您想要的任何方式。本指南將向您介紹基礎知識。
建立新頁面
探索儲存庫
訪問資產
存取數據
動態頁面
部署
全域變數
麵包師.config.js
第一步是點擊 GitHub 的「使用此範本」按鈕，為自己建立儲存庫的副本。
系統會要求您為您的專案提供一個 slug。完成後，將在https://github.com/your-username/your-slug上提供一個新的儲存庫。
接下來，您需要將其克隆到您的計算機上才能使用程式碼。
打開終端機並 cd 到代碼資料夾。將項目克隆到您的資料夾中。這會將項目複製到您的電腦上。
git 克隆 https://github.com/your-username/your-slug
如果該命令對您不起作用，可能是因為您的電腦設定不同，您需要使用 SSH 克隆到儲存庫。嘗試在終端機中執行此命令：
git clone [email protected]:你的使用者名稱/你的slug.git
儲存庫下載完成後，進入 your-slug 並安裝 Node.js 依賴項。
npm 安裝
安裝依賴項後，您就可以預覽專案了。執行以下命令來啟動測試伺服器。
npm 啟動
現在在瀏覽器中造訪localhost:3000 。您應該會看到一個可供自訂的樣板頁面。
另一種方法是使用 bluprint 建立新頁面，bluprint 是路透社圖形部門開發的命令列腳手架工具。
藍圖新增 https://github.com/datadesk/baker-example-page-template mkdir 我的新頁面cd 我的新頁面 藍圖開始麵包師範例頁面
以下是從我們的頁面範本複製新專案時您會找到的標準文件和資料夾。您將比其他文件花費更多的時間來處理某些文件，但是對它們的用途有一個大致的了解是有好處的。
資料資料夾包含項目的相關資料。我們使用這個資料夾來儲存每個項目所需的資訊——例如它應該存在的 URL。您還可以在此處儲存各種其他資料類型，包括.aml 、 .csv和.json 。
meta.aml檔案包含有關頁面的重要信息，例如標題、署名、slug、發布日期和其他欄位。填寫它可以確保您的頁面正確顯示並且可以被搜尋引擎索引。所有屬性的完整清單可以在我們的參考材料中找到。您可以擴展此選項以包含任意數量的選項。
此資料夾儲存我們網站的基本模板和可重複使用的程式碼片段。當您開始時，您不太可能在此處進行任何更改。在更進階的用例中，您可以在其中儲存跨多個頁面重複使用的程式碼。
base.htmlbase.html 檔案包含我們建立的每個頁面上的所有基本 HTML。這裡的範例在設計上是初級的。您可能希望在實際實施中包含更多內容。
工作區是您放置與專案相關但不需要在網路上發布的任何內容的地方。 AI 檔案、程式碼片段、寫作等等。
用於儲存媒體和其他資產，例如圖像、視訊、音訊static字體等。
JavaScript 檔案儲存在此資料夾中。 JavaScript 的主檔案稱為app.js ，您可以直接編寫程式碼。透過npm安裝的套件可以像其他 Node.js 腳本一樣導入和運行。您可以建立其他檔案來在此資料夾中編寫 JavaScript 程式碼，但必須確保該檔案是從app.js啟動的。
我們的樣式表是用 SASS 編寫的，SASS 是一種功能強大的樣式表語言，可以讓開發人員更好地控制 CSS。如果您對 SASS 不滿意，可以將純 CSS 寫入樣式表中。
styles 資料夾包含一個樣式表 ( app.scss )，您可以在其中將所有自訂樣式新增至專案中，但有時您可能想要製作其他樣式表並將它們匯入到app.scss中。此範例項目僅包含模擬簡單網站所需的最低限度。您可能希望在現實世界的實施中開始更多的工作。
baker.config.js檔案是我們放置 Baker 用於服務和建置專案的選項的位置。它已在本文件的其他地方完整記錄。除domain設定外，只有進階使用者才需要變更此檔案。
您頁面的預設模板。您將在此處佈置頁面。它使用 Nujucks 模板系統來建立 HTML。
這些文件追蹤我們專案中使用的節點依賴項。當您運行npm install時，您新增的庫將在此處自動追蹤。
這是一個特殊的目錄，用於儲存 GitHub 用於與我們的專案和程式碼互動的檔案。 .github/workflows目錄包含處理我們的開發部署的 GitHub Action。您無需在此處編輯任何內容。
作為部署過程的一部分，資產目錄中的檔案儲存進行了最佳化和雜湊處理。為了確保您對圖像和其他靜態檔案的引用，您應該使用{% static %}標記。這確保了文件在發佈時被大量緩存，並且圖像的連結在所有環境中都有效。您會想將它用於所有照片和影片。
<圖>
<img src="{% static 'assets/images/baker.jpg' %}" alt="貝克標誌" width=200>
</圖>儲存在_data資料夾中的結構化資料檔案可透過模板標籤或 JavaScript 存取。在此示範中，包含了一個名為example.json的檔案來說明可能性。支援其他文件格式，例如 CSV、YAML 和 AML。
_data資料夾中的檔案可依其名稱在範本中使用。因此，使用_data/example.json ，您可以撰寫以下內容：
{% 範例中的 obj %}
{{ obj.year }}: {{ obj.wheat }}{% endfor %}對於在 Baker 中建立專案的任何人來說，一個常見的需求是存取 JavaScript 檔案中的原始資料。通常，這些資料會傳遞到使用 d3 或 Svelte 編寫的程式碼中，以在頁面上繪製圖形或建立 HTML 表格。
如果您正在存取的資料已經在您信任的 URL 上可用，那麼這很容易。但如果不是，而且是您自己準備的資料呢？
可以存取 _data 資料夾中的記錄。唯一需要注意的是，將此文件轉換為可用狀態的工作是您的責任。 d3-fetch是一個很好的函式庫。
要以 Baker 理解的方式建立此文件的 URL，請使用以下格式：
import { json } from 'd3-fetch';// 第一個參數應該是檔案的路徑 // 第二個參數 *必須* 是「import.meta.url」 const url = new URL('../_data /example.json', import.meta.url);// 呼叫它inconst data = wait json(url);另一種方法是將資料作為script標記列印到模板中。 jsonScript過濾器接受傳遞給它的變量，對其運行JSON.stringify ，並將 JSON 輸出到<script>標記內的 HTML 中，並在其上設定您作為參數傳遞的 ID。
{{ 範例|jsonScript('範例資料') }}一旦完成，您現在可以透過 JavaScript 中的 ID 檢索儲存在頁面中的 JSON。
// 取得使用您在inconst dataElement = document.getElementById('example-data') 中傳遞的相同ID 建立的元素jsonScript;// 將該元素的內容轉換為JSON // 執行您需要對「data」執行的操作!const data = JSON.parse(dataElement.textContent);雖然建議使用 URL 方法，但當您試圖避免額外的網路請求時，此方法可能仍然是首選。它還具有不需要特殊函式庫即可將.csv資料轉換為 JSON 的額外好處。
您可以透過將結構化資料來源提供給baker.config.js檔案中的createPages選項來產生無限數量的靜態頁面。例如，此程式碼片段將為example.json檔案中的每筆記錄產生一個頁面。
導出預設值{
// ...為了說明這一點，上面的所有其他選項都已被排除
createPages: createPages(createPage, data) {// 從 _data 資料夾取得資料 const pageList = data.example;// 循環記錄 for (const d of pageList) { // 設定將用於每個物件的基本模板。它位於 _layouts 資料夾 const template = 'year-detail.html'; // 設定頁面的 URL const url = `${d.year}`; // 設定會傳遞到模板上下文的變數 const context = { obj: d }; // 使用提供的函數渲染頁面 createPage(template, url, context);}
},};這可用於使用單一範本建立類似/baker-example-page-template/1775/和/baker-example-page-template/1780/]的 URL。
在部署由此儲存庫建立的頁面之前，您需要設定您的 Amazon AWS 帳戶並在您的 GitHub 帳戶中新增一組憑證。
首先，您需要在 Amazon 的 S3 儲存服務中建立兩個儲存桶。一個用於您的暫存網站。另一個用於您的生產站點。對於這個簡單的範例，每個都應允許公共存取並配置為提供靜態網站服務。在一種更複雜的方案中，例如我們在《洛杉磯時報》運行的方案，這些存儲桶可以與註冊的域名相鏈接，並且通過身份驗證方案將暫存站點從公眾視野中屏蔽出來。
然後，這些儲存桶的名稱應儲存為 GitHub“秘密”，可供部署網站的操作存取。您應該存取您的帳戶或組織的設定面板。首先加入這兩個秘密。
| 姓名 | 價值 |
|---|---|
BAKER_AWS_S3_STAGING_BUCKET | 您的暫存儲存桶的名稱 |
BAKER_AWS_S3_STAGING_REGION | 建立臨時儲存桶的 S3 區域 |
BAKER_AWS_S3_PRODUCTION_BUCKET | 您的生產儲存桶的名稱 |
BAKER_AWS_S3_PRODUCTION_REGION | 建立生產儲存桶的 S3 區域 |
接下來，您應該確保您擁有來自 AWS 的金鑰對，該金鑰對能夠將公用檔案上傳到您的兩個儲存桶。這些值也應該添加到您的秘密中。
| 姓名 | 價值 |
|---|---|
BAKER_AWS_ACCESS_KEY_ID | AWS 存取金鑰 |
BAKER_AWS_SECRET_ACCESS_KEY | AWS 金鑰 |
此儲存庫中包含的 GitHub Action 將自動為每個分支發布一個暫存版本。例如，推送到預設main分支的程式碼將顯示在https://your-staging-bucket-url/your-repo/main/ 。
如果您要建立一個名為bugfix的新 git 分支並推送您的程式碼，您很快就會在https://your-staging-bucket-url/your-repo/bugfix/上看到一個新的暫存版本。
在即時發送頁面之前，您應該確定 URL 的最終位址。這將設定儲存桶中將發布頁面的子目錄。此功能允許《紐約時報》在同一個儲存桶中發布大量頁面，每個頁面由不同的儲存庫管理。
第一步是將 URL 的 slug 輸入到_data/meta.aml設定檔中。
slug：您的頁面 slug
確保你的子彈沒有被拿走絕對不是一個壞主意。您可以透過造訪https://your-production-bucket-url/your-slug/並確保它返回頁面未找到錯誤來做到這一點。
如果您想在儲存桶的根部發布頁面，則可以將 slug 保留為空。
蛞蝓：
接下來，將變更提交到設定文件，並確保將其推送到 GitHub 上的主分支。
git add _data/meta.aml git commit -m“設定頁面slug” git推送原點主要
造訪 GitHub 上儲存庫頁面的發布部分。您可以在儲存庫的主頁上找到它。
起草新版本。
您將在此處建立一個新的標籤號碼。一個好的方法是從遵循語義版本控制標準的 xxx 格式編號開始。 1.0.0 是一個好的開始。
最後，點擊底部的綠色大按鈕並發送版本。
等待幾分鐘，您的頁面應該顯示在https://your-production-bucket-url/your-slug/ 。
Baker 測試伺服器可以透過以下選項開始記錄更詳細的資訊。
調試=1 npm 啟動
要將日誌限制為 Baker 運行：
調試=麵包師傅:* npm start
如果您的建置不成功，您可以嘗試透過終端機在本機上自行建立靜態網站。如果頁面建置出現錯誤，它們將會列印到您的終端上。
npm 運行構建
Baker 附帶了一組在它創建的每個頁面上都相同的全域變量，以及另一組基於當前創建的頁面設定的特定於頁面的變數。您可以使用這些變數有條件地在頁面上新增內容或根據目前頁面過濾掉不相關的資料。
NODE_ENV NODE_ENV變數總是兩個值之一： development或production 。它對應於頁面上正在運行的建置類型。
當您執行npm start時，您處於development模式。當您執行npm run build時，您處於production模式。
只有當您處於development模式時，這對於向頁面添加內容最有用。
{% if NODE_ENV == 'development' %}<p>您永遠不會在實際網站上看到此內容！DOMAIN DOMAIN變數將始終與baker.config.js中傳遞的domain選項相同，如果未傳遞，則為空字串。
PATH_PREFIX PATH_PREFIX變數將始終與baker.config.js中傳遞的pathPrefix選項相同，如果未傳遞，則為單一正斜線 ( / )。
page.url目前頁面的項目相對 URL。如果baker.config.js檔案中提供了pathPrefix，則將包含pathPrefix - 換句話說，它將考慮正在完成的任何專案路徑並指向專案中的正確頁面。
page.absoluteUrl當前頁面的絕對 URL。這會將domain 、 pathPrefix和目前路徑組合成一個完整的URL。目前用於輸出規格 URL 和社交<meta>標籤的所有 URL。
<link rel="canonical" href="{{ page.absoluteUrl }}">page.inputUrl這是用於建立此頁面的原始範本相對於目前專案目錄的路徑。如果您的 HTML 檔案位於page-two/index.html ，則page.inputUrl將為page-two/index.html 。
page.outputUrl這是為建立此頁面而輸出的 HTML 檔案相對於_dist資料夾的路徑。如果您有一個位於page-two.html的 HTML 文件， page.outputUrl將為page-two/index.html 。
我們從事的每個 Baker 專案的根目錄中都包含一個baker.config.js檔案。該文件負責將資訊傳遞給 Baker，以便它可以正確建立您的專案。
導出預設值{
// 資產所在目錄
資產：“資產”，
// 建立頁面
建立頁面：未定義，
// 資料目錄
資料：'_data'，
// 用於建置路徑的可選自訂網域
域：未定義，
// 每個 JavaScript 入口點的路徑或一組路徑
入口點：'scripts/app.js',
// 整體輸入目錄，通常是目前資料夾
輸入：process.cwd(),
// 範本佈局、巨集和包含所在的位置
佈局：'_layouts'，
// 一個對象，其中包含全域變數的鍵和值
// 傳遞給所有 Nunjucks 模板
nunjucks變數：未定義，
// 一個鍵（名稱）+值（函數）的對象，用於新增自訂
// 過濾 Nunjucks
nunjucksFilters：未定義，
// 一個鍵（名稱）+值（函數）的對象，用於新增自訂
// Nunjucks 的標籤
nunjucks標籤：未定義，
// 編譯後的檔案輸出到哪裡
輸出：'_dist'，
// 新增到每個解析路徑開頭的前綴，如何新增
// 蛞蝓工作
路徑前綴: '/',
// 一個可選目錄，用於放置所有資源，很少使用
靜態根：''，}；預設值： ”assets”
這告訴 Baker 將哪個資料夾視為資產目錄。您可能不必更改此設定。
預設值： undefined
createPages是一個可選參數，可以使用專案中的資料和範本動態建立頁面。
導出預設值{
// …
// createPage - 傳入範本、輸出名稱和資料上下文
// data - `_data` 資料夾中準備好的數據
createPages(createPage, data) {for (const title of data.titles) { createPage('template.html', `${title}.html`, {context: { title }, });}
},};預設值： ”_data”
data選項告訴 Baker 將哪個資料夾視為其資料來源。您可能不需要更改此設定。
預設值： undefined
domain選項告訴 Baker 在建立絕對 URL 時要使用什麼。 bakery-template將其預設為https://www.latimes.com 。
預設值： ”scripts/app.js”
entrypoints選項告訴 Baker 將哪些 JavaScript 檔案視為腳本包的起點。這可以是檔案或檔案全域的路徑，從而可以同時建立多個套件。
預設值： process.cwd()
input選項告訴貝克將哪個資料夾視為整個專案的主目錄。預設情況下，這是baker.config.js檔案所在的資料夾。
預設值： ”_layouts”
layouts選項告訴 Baker 範本、包含內容和巨集的位置。預設情況下，這是_layouts資料夾。您可能不需要設定此項。
預設值： undefined
您可以使用nunjucksFilters傳入您自己的自訂過濾器。在物件中，每個鍵都是過濾器的名稱，函數值是使用過濾器時呼叫的函數值。
導出預設值{
// ...
// 傳遞一個過濾器物件以新增到 Nunjucks
nunjucksFilters: {square(n) { n = +n; 返回n*n；}
},} {{值|平方}}預設值： undefined
您可以使用nunjucksTags傳入您自己的自訂標籤。它們與過濾器的不同之處在於它們使輸出文字或 HTML 區塊變得更容易。
導出預設值{
// ...
// 傳遞一個過濾器物件以新增到 Nunjucks
nunjucksTags: {doubler(n) { return `<p>${n} 加倍為 ${n * 2}</p>`;}
},}; {% 加倍值 %}預設值： ”_dist”
output選項告訴 Baker 當npm run build執行時將檔案放在哪裡。預設情況下，這是_dist資料夾。您可能不需要設定此項。
預設: ”/”
pathPrefix告訴 Baker 要將什麼路徑前綴添加到它構建的任何 URL 中。如果也傳遞了domain ，則在建置絕對URL時它將與pathPrefix結合。您通常不會手動設定它 - 它在部署期間用於使用專案 slugs 建立 URL。
預設: ””
staticRoot選項指示 Baker 將所有資源放入附加目錄中。這對於需要在每個頁面上具有唯一的 slugs 而無需嵌套的項目非常有用，從而允許它們共享靜態資源。然而，這是一種特殊情況，需要自訂部署設定。如果沒有充分的理由，請勿嘗試使用此功能。
