在 Slipway 站点上编写页面和文章
一个 Slipway 站点是由 Markdown 文件和一段 Front Matter 构成的。布局（Layout）负责其余工作：标题、页面标题、目录、日期和语言切换器。你需要按照模式（Schema）填写 Front Matter，并用纯 Markdown 撰写正文。如果站点包含 AGENTS.md，请优先阅读它；当其内容与本技能冲突时，以 AGENTS.md 为准。
1. 获取基线
将主题的检查文件克隆到站点文件夹之外的一个目录：
git clone --depth 1 https://github.com/arminazimi/slipway "$HOME/.slipway"
cd "$HOME/.slipway" && npm ci && cd -
在进行任何更改之前运行第6节，并保存输出。编辑完成时，不应引入任何新问题或发现。
2. 选择布局和文件
| 你要编写的内容 | layout | 文件 |
|---|---|---|
| 普通页面（关于、联系） | page | <文件夹>/<页面>.md，访问地址为 /<文件夹>/<页面>.html |
| 带有侧边栏的文档页面 | doc | 任意文件夹，通常为 docs/<页面>.md，需要设置 permalink |
| 带日期的文章 | post | _posts/<日期>-<slug>.md，其中 <日期> 格式为 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（格式与文件名中的日期相同）：文章会显示“编辑于”，并且 feed、站点地图和结构化数据都会将其报告为最后修改日期。
3. 按照模式填充 Front Matter
每个键、其类型及其允许的值都在 reference/front-matter.md 中，该文件是根据检查所使用的模式自动生成的。只使用该文件中为你的布局列出的键。
title是必需的，不能为空。布局将其打印为页面标题。- 添加
description：一个句子，用于搜索结果和链接预览。 tags和categories是列表：tags: [release, notes]。- 文章中的
author是_data/authors.yml中的一个键，或者是一个键的列表（用于多位作者）：author: [ada, sam]。如果键在该文件中缺失，请先在该文件中添加作者。 - 文章中的
series将其放入一个系列：在每个部分中使用完全相同的名称，series: Writing for the web。各部分按日期排序。 permalink以/开头。对于默认语言的文章，可以省略它；站点的配置会设置地址。- 对于非站点默认语言（
_config.yml中的lang）的页面，以及每个有翻译的页面，请设置lang。 - 仅适用于
home：cta_text和cta_url必须同时出现，或者都不出现。variant选择外观：editorial（默认）、landing（需要添加features，每个包含title）、blog或docs（从_data/navigation.yml的docs列表中生成卡片）。 - 如果值包含
:或以 YAML 特殊处理的字符开头（[、{、*、&、!、#、|、>、@或反引号），请用引号括起来。
4. 编写正文
- 仅使用纯 Markdown。永远不要使用 Liquid：不要使用
{{ }}和{% %}，即使在代码块中也不行。布局已经添加了 Liquid 的功能。 - 章节从
##开始。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: 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。在波斯语文本中，使用波斯语的 ی 和 ک（而不是阿拉伯语的 ي 和 ك），在 میشود 等单词中使用零宽非连接符，并使用波斯语标点（، 和 ؟）。将命令、文件名和代码放在反引号中：它们在句子中保持从左到右的显示。
6. 检查编辑
在站点文件夹中，根据模式检查每个页面的配置和 Front Matter：
node "$HOME/.slipway/tools/theme/validate.mjs" .
每个问题都会以 文件:行号 键: 消息 (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；要么更改共享它的所有页面，要么一个都不改。 - 绝不重命名或移动已发布的页面或文章来更改其标题；请设置
title。它的地址是其文件名或permalink，更改会破坏指向它的链接。 - 绝不对编辑
_site/，也绝不删除具有 Front Matter 且无正文的页面。 - 绝不编辑主题布局或包含文件来更改单个页面的外观。