keystone ssg

警告

Keystone 現在看起來已經過時了，我建議您看看 Astro 或 Vite。

---

為什麼選擇梯形？

Keystone 是一款靜態網站產生器，非常適合快速建立小型網站。無需設置，預設會啟用一系列方便的功能。

特徵

• 輕鬆安裝和設置，只需一個命令即可開始使用
• 自動刷新開發伺服器
• 使用模板和可重複使用的部分/導入，帶有插槽
• 自動路由，只需上傳/public即可開始
• 預設啟用 Babel、SCSS 和 Markdown 支持，開發模式下的來源映射
• JS 和 CSS 縮小和捆綁（使用 Rollup）
• 動態連結載入（無需重新載入頁面）
• 搜尋索引檔案產生器，方便網站搜尋

入門

安裝

建立一個新目錄並執行以下命令來設定 Keystone、package.json 和 git。需要節點 14.xx。

 $  npm install keystone-ssg

太棒了，你已經安裝好了！

開發伺服器

啟動 Keystone 開發伺服器，然後造訪 http://localhost:8080 查看範例網站。

 $ npm run dev

建構專案

運行命令後，項目將在/public資料夾中構建，準備上傳。

 $ npm run build

建立您的網站

Keystone 專案中有六個重要的目錄，每個目錄都有自己的用途：

頁數

頁面資料夾中的每個 HTML .html和 markdown .md檔案都對應到您網站上的一個頁面。這裡的範例專案中有兩個文件，嘗試開啟index.html 。自動路由將在執行npm run build時將檔案捆綁到/public資料夾，如下所示：

 /pages/index.html   ->  /public/index.html
/pages/example.md ->  /public/example/index.html

您可能已經注意到， index.html具有以下標記： <_template basic.html /> 。這會將index.html的內容放置在位於/templates/basic.html的開槽模板檔案中。這種自訂 HTML 標記格式也適用於.md檔。

範本

模板可以與/pages一起使用，為您的頁面提供現成的框架。在範本檔案中使用<_slot />標記為您的內容提供入口點。打開/templates/basic.html並尋找：

 < _var title default="Keystone default title" />

這是模板檔案中名為title的變數槽，具有可選的預設值。

使用以下內容作為/pages內的範本標籤將允許您從內容頁面將自訂值輸入到範本中：

 < _template basic.html title="A custom title" /> 

成分

/components夾僅用於可重複使用元件。 <_import>標籤用於將元件匯入其他 HTML 檔案中，其中的範例位於/templates/basic.html中。

 < _import header.html />

在先捆綁原始程式碼之後， <_import>標籤也可以用於匯入任何其他類型的檔案（JS、SCSS 等）的內容。

原始碼

將 Javascript 檔案放置在/src資料夾中。以下標籤將轉換為常規<script>匯入標籤，連結到您的檔案/src/main.js ：

 < _script main.js />

完全支援 ES6 匯入，產生的檔案將使用 Babel 進行轉譯，與 Rollup 捆綁並縮小。

風格

/styles資料夾用於您的 CSS/SCSS。以下標記將轉換為常規<link> css 導入標記，連結到已編譯的/styles/main.scss檔：

 < _style main.scss />

完全支援所有node-sass功能，包括@import 。

資產

靜態資源放置在這裡，即字體、圖像、圖示。這裡的所有內容都會轉移到根目錄中相應的資料夾中，例如：

 /assets/favicon.ico -> /public/favicon.ico
/assets/fonts/fontname.ttf -> /public/fonts/fontname.ttf

筆記

Keystone HTML 標籤

• 每個自訂 Keystone HTML 標記都可以在 HTML 檔案中的任何位置使用，甚至在其他 HTML 屬性中（除了其他 Keystone 標記之外）。
• 或者，對於所有自訂 Keystone 標記，您可以使用 src 屬性來定位任何資料夾中的檔案： <_template src='myfolder/myfile.html' /> 。
• 所有路徑都相對於包含package.json的資料夾，除非您想要存取專案外部的文件，否則請勿使用開頭的斜杠。
• Keystone HTML 標記屬性可以使用「單」、「雙」或「反引號」引號。

動態載入

• 動態載入取得本地網站連結並用新頁面取代目前頁面的內容，無需重新載入和切換頁面。
• 啟用動態載入時，使用後退按鈕時不會儲存頁面狀態（例如輸入值、捲動位置）。
• 點擊連結時， .keystone-page-loading類別將設定為display: block 。如果該類別在 CSS 中設定為display: none ，則可以使用它來建立載入指示器。
• 在 keystone.config.js 中停用動態載入。

搜尋索引產生器

• 搜尋索引產生器在根目錄中產生一個檔案search.json 。
• 所有 HTML 標籤都會從頁面中剝離，只保留和儲存文字。
• 該文件可以透過網站搜尋功能取得和查詢，以輕鬆找到哪個頁麵包含哪些內容。
• 在 keystone.config.js 中停用搜尋欄助手。

各種各樣的

• public資料夾被 Git 忽略，如果您希望使用公共行將其提交到 Git，請從.gitignore中刪除public行。

更新梯形校正

• 將package.json中的版本號替換為您要更新到的版本，然後執行npm install keystone-ssg ，以進行快速升級。

應用程式介面

標籤

標籤	描述	屬性
<_template>	將目前檔案匯入到範本檔案中的<_slot>中	[檔名],[變數名],src
<_slot>	在範本檔案中用作匯入檔案的入口點	沒有任何
<_var>	在模板檔案中使用，替換為取自<_template>的變數	[變數名稱]，預設
<_import>	導入一個元件	[檔名]，src
<_script>	建立連結到捆綁腳本的<script>標記	[檔名]，src
<_style>	建立一個連結到捆綁的 css 檔案的<link>標籤	[檔名]，src

NPM 指令

命令	描述	輸出差異
npm run dev	建立用於開發的網站，然後啟動 Keystone 開發伺服器。	產生內聯源映射。 開發伺服器腳本已註入。
npm run build	建立用於生產的網站。	捆綁包被壓縮和縮小。

設定檔

設定檔是keystone.config.js

選項	描述	預設
動態連結	在您的 Keystone 網站上啟用動態加載的本地鏈接，無需刷新	真的
搜尋文件	在根目錄產生search.json	真的
索引路徑	您網站的根目錄	'/'
港口	開發伺服器端口，本地主機： 8080	8080
埠Ws	用於開發伺服器的第二個端口	8081
開發伺服器IP	開發伺服器的位置，本地主機：8080。替換為您裝置的本機 IP 以查看本機裝置上的開發伺服器（例如：「192.168.1.103」）。	'本地主機'
看過	Keystone 開發伺服器監視的目錄，在編輯檔案時將強制重新編譯和頁面刷新	['模板'、'頁'、'資產'、'組件'、'src'、'樣式']
建造	內容頁面目錄	“頁面”
服務	包含生成的網站的目錄	'民眾'
完全重新編譯	在開發模式下每次文件更改後強製完全重新編譯所有文件	錯誤的

預設目錄佈局

 | empty-keystone-project
--| .git/
--| assets/
--| components/
--| pages/
--| src/
--| styles/
--| templates/
--| keystone.config.js
--| package.json
--| package-lock.json

插件錯誤

如果安裝並運行範例後出現 PLUGIN_ERROR，這是 Babel 問題，請執行以下命令來修復它：

 npm install @babel/core @babel/preset-env --save-dev