在 Slipway 網站上撰寫頁面和文章
Slipway 網站是由 Markdown 檔案和一塊 front matter 組成的。版面會處理其餘部分：標題、標題、目錄、日期和語言切換器。您根據結構定義撰寫 front matter，並用純 Markdown 撰寫文字。如果網站有 AGENTS.md，請先閱讀它；它與此技能不同的部分以此技能為準。
1. 取得基準線
先一次性取得主題的檢查檔案，放在網站以外的資料夾中：
git clone --depth 1 https://github.com/arminazimi/slipway "$HOME/.slipway"
cd "$HOME/.slipway" && npm ci && cd -
在您進行任何更改前執行第 6 節，並保留輸出。當您的編輯沒有新增任何問題和任何發現時，編輯才算完成。
2. 選擇版面與檔案
| 您正在撰寫的內容 | layout | 檔案 |
|---|---|---|
| 一般頁面（關於、聯絡） | page | <folder>/<page>.md，網址為 /<folder>/<page>.html |
| 含側邊欄的文件頁面 | doc | 任意資料夾，通常是 docs/<page>.md，需有 permalink |
| 有日期的文章 | post | _posts/<date>-<slug>.md，其中 <date> 格式為 YYYY-MM-DD |
| 首頁 | home | index.md |
文章的檔案名稱就是它的日期和網址；要更改標題請設定 title，切勿重新命名檔案。doc 頁面只有在 _data/navigation.yml 中的 docs 清單連結了它的 permalink 時才會顯示在側邊欄中；請按閱讀順序將它加入其中。請不要建立 search.json、feed.xml、sitemap.xml、404.md、tags.md 或 archive.md：這些檔案已經存在，而且它們刻意只有 front matter 而沒有文字。
關於文章的草稿、排程文章和編輯：草稿放在 _drafts/<slug>.md 中，檔案名稱不含日期——GitHub Pages 永遠不會建置 _drafts/，而 jekyll serve --drafts 會以今天的日期預覽它。排程文章是一般的文章，但其 YYYY-MM-DD 檔案名稱是未來的日期：GitHub Pages 會在該日期自動發布它，而 jekyll serve --future 會提前預覽它，並在頁面上標記為「已排程」。在對已發布的文章進行大量編輯後，請加上 updated: YYYY-MM-DD（格式與檔案名稱的日期相同）：文章會顯示「編輯於」的資訊，而摘要、網站地圖和結構化資料會將其報告為最後修改日期。
3. 根據結構定義填寫 front matter
每個鍵、其型別和允許的值都在 reference/front-matter.md 中，該檔案是從檢查工具使用的結構定義產生的。只使用它為您的 layout 列出的鍵。
title是必填且不得為空。版面會將其列印為頁面標題。- 加上
description：一句話，用於搜尋結果和連結預覽。 tags和categories是清單：tags: [release, notes]。- 文章中的
author是_data/authors.yml中的一個鍵，或是多個作者的鍵清單：author: [ada, sam]。如果該鍵在該檔案中找不到，請先在那裡加入作者。 - 文章中的
series將其放入系列中：在每個部分使用完全相同的名稱，series: Writing for the web。各部分按日期排序。 permalink以/開頭。在預設語言的（default language）文章中請省略它；網站的配置會設定網址。- 在非網站預設語言（
_config.yml中的lang）的頁面上設定lang，並且在每個有翻譯版本的頁面上也設定lang。 - 僅限
home：cta_text和cta_url要一起使用，否則就都不使用。variant選擇外觀：editorial（預設）、landing（加上features，每個都有title）、blog或docs（從_data/navigation.yml的docs清單中產生卡片）。 - 如果值包含
:或開頭是 YAML 特殊處理的字元（[、{、*、&、!、#、|、>、@或反引號），請用引號括起來。
4. 撰寫主體
- 僅限純 Markdown。絕對不要使用 Liquid：沒有
{{ }}和{% %}，即使在程式碼區塊中也不行。版面已經加入了 Liquid 會做的所有事情。 - 從
##開始章節。h1是標題；主體中的一個#標題會產生第二個h1。 - 保持標題層級順序（
##，然後###），以便目錄和「使用您的代理編輯」按鈕能找到每個章節。 - 連結到其他頁面時使用網址，而非檔案：
[安裝](/docs/install/)、[關於](/about.html)。 - 圖片放在
assets/中；每張圖片都要有替代文字：。 - 若要讓頁面更寬，請在 front matter 中設定
width: narrow、wide或full。若要只放寬一個區塊（表格、圖片、圖形），請將其包在一個帶有類別sl-wide（最寬 64rem）或sl-bleed（邊到邊）的 HTML 元素中：<figure class="sl-wide"><img src="/assets/map.png" alt="路線地圖"></figure>。doc版面會將章節保留在它的欄位中。 - 為程式碼區塊指定語言（
```yaml），以便它們能高亮顯示，並在從右到左的頁面中保持從左到右閱讀。
通過結構定義的範例：
- examples/doc-page.md：一個
doc頁面。 - examples/post.md：一篇帶有標籤的文章。
- examples/post-fa.md：同一篇文章的波斯語版本。
每個範例中的第一個註解說明了檔案應放置的位置。
5. 新增翻譯
- 該語言必須存在於
_config.yml的slipway.languages中，並包含code、name和prefix（例如/fa）。如果缺少該語言，請在新增語言之前先詢問：這會更改每個頁面的切換器。 - 如果原文還沒有
translation_key，請為其新增一個，例如plain-markdown，並且如果還沒有lang，也請設定lang（lang: en）：切換器透過這兩個值來找到翻譯。為翻譯版本設定相同的translation_key。這會將兩者在語言切換器和網站地圖中連結起來。 - 將
lang設定為語言代碼，並將permalink設定為前綴下的網址：/fa/plain-markdown/。 - 檔案放置位置：頁面放在前綴資料夾中（
fa/about.md）；文章則留在_posts/中，使用自己的 slug（_posts/2026-10-20-plain-markdown-fa.md）。 - 翻譯
title、description、tags和主體。保持layout、日期、程式碼、命令和 URL 不變。 - 如果網站有該語言的標題選單（
_data/navigation.yml中的main_fa），也請將頁面加入其中。
從右到左的語言（fa、ar、he、ur）會根據 lang 獲得從右到左的版面；請不要設定 direction 或 dir。在波斯語文字中，使用波斯語的 ی 和 ک（而非阿拉伯語的 ي 和 ك），在諸如 میشود 等詞語中使用零寬度非連接符（zero-width non-joiner），以及使用波斯語標點符號（، 和 ؟）。將命令、檔案名稱和程式碼放在反引號中：它們在句子內保持從左到右。
6. 檢查編輯
從網站資料夾中，根據結構定義檢查每個頁面的配置和 front matter：
node "$HOME/.slipway/tools/theme/validate.mjs" .
每個問題都會以 file:line key: message (allowed: ...) 的格式列印出來。請在該行修正它，使用允許的值，然後再次執行。接著，如果網站有 Gemfile，請建置網站：
bundle exec jekyll build
閱讀每個錯誤和警告，並在其指出的檔案中進行修正。然後在原始碼和建置輸出上執行 doctor。它會根據可代理編輯的規範檢查網站：AGENTS.md、content-schemas.json（當網站有該檔案時，它會根據其指定的結構定義驗證您的 front matter）、來源映射和編輯提示：
node "$HOME/.slipway/packages/doctor/bin/slipway.mjs" doctor . --build _site
將其發現與您的基準線進行比較。一個提及您檔案名稱的發現是您需要修正的。如果沒有 Gemfile，請在沒有 --build 的情況下執行 doctor，並在推送後閱讀 Pages 建置的記錄。
絕不
- 絕對不要在頁面中使用 Liquid（
{{ }}或{% %}）。 - 絕對不要新增 reference/front-matter.md 中未列出的 front matter 鍵。
- 絕對不要只更改一個翻譯版本的
translation_key；要更改就更改所有共用該translation_key的頁面，否則都不要更改。 - 絕對不要重新命名或移動已發布的頁面或文章來更改其標題；請設定
title。它的網址就是它的檔案名稱或permalink，連結到它的連結會因此而中斷。 - 絕對不要編輯
_site/，也絕對不要刪除一個有 front matter 但沒有文字的頁面。 - 絕對不要編輯主題版面或包含檔案來更改單一頁面的外觀。