<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Banyan</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/</link><description>Recent content on Banyan</description><generator>Hugo</generator><language>zh-Hans</language><lastBuildDate>Mon, 16 Nov 2026 00:00:00 +0800</lastBuildDate><atom:link href="https://f6e67316.banyan-git-test.pages.dev/zh/index.xml" rel="self" type="application/rss+xml"/><item><title>外观 · 配色与首页定制</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/appearance-customization/</link><pubDate>Sun, 15 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/appearance-customization/</guid><description>&lt;p&gt;先完成&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/site-configuration/"&gt;站点基本设置&lt;/a&gt;，再按需要修改外观。只改首页文字时，直接阅读“最小首页艺术包”或“首页信号”。&lt;/p&gt;&#10;&lt;h2 id="palette"&gt;配色&lt;/h2&gt;&#10;&lt;p&gt;编辑 &lt;code&gt;hugo.toml&lt;/code&gt; 中已有的配色设置；文件路径相对于 &lt;code&gt;assets/&lt;/code&gt;：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-toml" data-lang="toml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;params&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;appearance&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;palette&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;site/theme.css&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;站点自行维护完整配色，Module 不提供默认配色。&#10;默认使用 &lt;code&gt;site/theme.css&lt;/code&gt;。需要高对比外观时，把上面的值改为 &lt;code&gt;site/theme.high-contrast.css&lt;/code&gt;。&#10;三套参考配色（默认、高对比度、Rose）都包含浅色和深色，不改变彩色图片。标题线的定制示例见各配色文件中的变量注释。&#10;自定义文件如 &lt;code&gt;assets/site/theme-custom.css&lt;/code&gt;，配置为 &lt;code&gt;palette = &amp;quot;site/theme-custom.css&amp;quot;&lt;/code&gt;。&#10;修改后重新构建并部署；外观页继续在所选配色中切换跟随系统、浅色和深色。&lt;/p&gt;&#10;&lt;h3 id="自定义配色"&gt;自定义配色&lt;/h3&gt;&#10;&lt;p&gt;复制完整配色文件后修改颜色，并将 &lt;code&gt;palette&lt;/code&gt; 指向该文件。&#10;同路径文件整体替换，不按 CSS 声明合并。配色文件维护颜色角色及其浅色、深色值，条目圆角使用 &lt;code&gt;--item-radius&lt;/code&gt;，表头线可指定颜色及是否占位；列表结构、动画和交互规则保留在组件中。&#10;&lt;code&gt;--item-current-marker&lt;/code&gt; 控制当前项起始边线的颜色，设为 &lt;code&gt;transparent&lt;/code&gt; 隐藏；保留标记宽度。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;.item-list&lt;/code&gt; 的 &lt;code&gt;--list-header-border&lt;/code&gt; 和 &lt;code&gt;.prose&lt;/code&gt; 的 &lt;code&gt;--prose-heading-border&lt;/code&gt; 使用完整边框声明：&lt;code&gt;none&lt;/code&gt; 取消线条和占位，&lt;code&gt;1px solid transparent&lt;/code&gt; 隐藏线条并保留占位，&lt;code&gt;1px solid #888&lt;/code&gt; 显示线条。单独定制正文栏标题线时，有目录按钮的页面在 &lt;code&gt;.document-heading&lt;/code&gt; 中设置该变量，其余页面在 &lt;code&gt;.prose &amp;gt; h1.column-heading&lt;/code&gt; 中设置。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;作用域&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;颜色用途&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;:root&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;页面背景、正文、弱化文字、边框、强调色、链接和焦点&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.icon&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;彩色图标的强调色和阴影；线条图标仍使用 &lt;code&gt;currentColor&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.item-control&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;普通、已访问、悬停、焦点和当前项的文字、背景及边框&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.item-list&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;列表标题和第一列首项的表头线&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.prose&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;标题、分隔线、删除文字、代码、引用、图片、表格和语法高亮&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.home-art-wind&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;风场艺术包中的锚点、地平线、信号和风向袋&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;无模式限定的作用域用于浅色和深色；深色规则只覆盖不同的值。&#10;在对应作用域中修改颜色，并同时检查浅色和深色规则。&#10;例如，修改表头背景时，替换已有的两处声明：&lt;/p&gt;</description></item><item><title>03 首次部署</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/deploying/</link><pubDate>Sat, 14 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/deploying/</guid><description>&lt;p&gt;先完成&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/site-configuration/"&gt;02 设置自己的站点&lt;/a&gt;。本页的 PowerShell 命令从站点根目录运行，并使用&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/getting-started/"&gt;开始使用&lt;/a&gt;中定义的 &lt;code&gt;swban&lt;/code&gt; 简称。引号中的 &lt;code&gt;&amp;lt;正式网址&amp;gt;&lt;/code&gt; 是需要替换的占位符。&lt;/p&gt;&#10;&lt;h2 id="选择部署方式"&gt;选择部署方式&lt;/h2&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;方式&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;需要提供&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;适用情况&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;本地构建后上传&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;检查通过的 HTML 和资源目录&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;先在本机完成构建，再发布&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Git 托管构建&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;站点源码仓库与平台构建配置&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;推送代码后由平台自动构建和发布&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;用 &lt;code&gt;swban help/zh deploy&lt;/code&gt; 查看按平台和方式划分的准备专项。Banyan 提供静态站点构建、交付配置生成和检查；账号授权、云项目创建、上传及 Git 接入由 &lt;a href="https://github.com/SwawHQ/swaw-clouds"&gt;Swaw Clouds&lt;/a&gt; 的专项说明指导。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;平台&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;Banyan 提供的配置&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;平台操作说明&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Cloudflare Pages&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;_headers&lt;/code&gt;、&lt;code&gt;_redirects&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;a href="https://github.com/SwawHQ/swaw-clouds/blob/main/skills/swaw-clouds/tasks/cloudflare/deploy/pages-upload/help.json"&gt;上传产物&lt;/a&gt; · &lt;a href="https://github.com/SwawHQ/swaw-clouds/blob/main/skills/swaw-clouds/tasks/cloudflare/deploy/pages-git/help.json"&gt;Git 托管构建&lt;/a&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;EdgeOne Makers&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;edgeone.json&lt;/code&gt; 交付规则&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;a href="https://github.com/SwawHQ/swaw-clouds/blob/main/skills/swaw-clouds/tasks/edgeone/deploy/upload/help.json"&gt;上传产物&lt;/a&gt; · &lt;a href="https://github.com/SwawHQ/swaw-clouds/blob/main/skills/swaw-clouds/tasks/edgeone/deploy/git/help.json"&gt;Git 托管构建&lt;/a&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;其他静态托管、对象存储与 CDN&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;HTML、资源和浏览器端 SW 策略&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;按目标平台配置响应头、重定向和缓存；Banyan 暂不生成这些平台的专用配置&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;两种方式使用同一套源码。上传方式交付产物目录；Git 方式交付源码和构建参数。切换前，按对应专项核对平台是否允许复用原项目。&lt;/p&gt;&#10;&lt;p&gt;在所选平台建立账号并确定目标项目。将 &lt;code&gt;hugo.toml&lt;/code&gt; 的 &lt;code&gt;baseURL&lt;/code&gt; 设为要公开使用的网址；若首次上传后才取得平台域名，取得后回填该值，重新构建并上传。绑定自有域名后也要更新它。&lt;/p&gt;&#10;&lt;h2 id="设置平台"&gt;设置平台&lt;/h2&gt;&#10;&lt;p&gt;编辑已有的 &lt;code&gt;assets/site/delivery.toml&lt;/code&gt;，找到 &lt;code&gt;[platform]&lt;/code&gt; 下的开关。只使用 Cloudflare Pages 时：&lt;/p&gt;</description></item><item><title>参考 · 项目术语表</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/glossary/</link><pubDate>Fri, 13 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/glossary/</guid><description>&lt;p&gt;对话和文档优先使用下表名称。机制名称带上作用范围；上下文明确时可用简称。对应标识用于查找配置或实现。&lt;/p&gt;&#10;&lt;h2 id="页面区域"&gt;页面区域&lt;/h2&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;术语&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;含义&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;对应标识&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;根导航列&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;页面第一列，显示首页和已发布的根页面入口。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.page-rail&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;根入口&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;根导航列中的一个条目，指向首页、顶层栏目或独立根页面。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;data-root-href&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;面包屑列&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;显示浏览路径中某一级栏目的条目，供用户选择同级内容。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.breadcrumb-column&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;主内容列&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;显示当前页面的文章、列表或其他主要内容。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.page-content&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;文档辅助列&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;容纳文章元信息和章节目录的页面列。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.document-aside&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;文章元信息&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;说明文章的目录归属、日期及相关链接等信息。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.document-meta&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;章节目录&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;由当前文章的章节标题组成的跳转列表。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.document-toc&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;主列表&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;当前集合页面在主内容列中显示的条目列表。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-browse/collection/render.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;结构面包屑&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;按页面真实内容层级生成的路径数据，用于 SEO 等输出。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;BreadcrumbList&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;页面画幅&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;横向排列根导航列、面包屑列和阅读组的整体区域。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.page-shell&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;阅读组&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;将主内容列和文档辅助列组合在一起的布局区域。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;.reading-group&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;搜索页&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;在根导航列输入关键词，并在正文宽度的主内容列显示当前语言的搜索结果。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;page-search&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;图片墙&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;用封面卡片呈现分类或文章的集合视图。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;page-collection-wall&lt;/code&gt;、&lt;code&gt;page-collection-wall-all&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;区域配置见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/layout-slots/"&gt;页面区域与布局&lt;/a&gt;，组件和样式见 &lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/ui-naming/"&gt;UI 命名与职责&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="内容与路径"&gt;内容与路径&lt;/h2&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;术语&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;含义&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;对应标识&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;分类&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;按主题或用途组织内容的方式，通过栏目层级和文章引用实现。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;内容目录、&lt;code&gt;_map.toml&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;栏目&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;组织子栏目、文章和引用的内容节点。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;_index.md&lt;/code&gt;、&lt;code&gt;section&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;文章&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;保存一篇正文及其元信息的内容页面，也可用于介绍产品。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;index.md&lt;/code&gt;、&lt;code&gt;page-article-*&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;页面包&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;将页面文件与图片等资源放在同一目录中的内容单元。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;含 &lt;code&gt;index.md&lt;/code&gt; 或 &lt;code&gt;_index.md&lt;/code&gt; 的目录&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;栏目文章引用&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;在栏目中收录已有文章，条目链接指向原文。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;_map.toml&lt;/code&gt; 中的 &lt;code&gt;refs&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;文章默认归属&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;由文章实际所在目录确定的栏目路径。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;文章的内容祖先&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;多维分类&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;将同一篇文章放入多个分类路径；正文保存在文章默认归属下，其他栏目通过引用收录。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;_map.toml&lt;/code&gt;、&lt;code&gt;refs&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;汇总列表&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;汇集指定栏目及其子栏目中的文章和引用，同一篇文章计入一次。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;params.aggregate&lt;/code&gt;、&lt;code&gt;page-collection-*-all&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;汇总时间范围&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;按文章更新时间划分汇总内容的区间，包含起点，截止到终点之前。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;params.time_range&lt;/code&gt;、&lt;code&gt;Lastmod&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;内容路径&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;页面在内容树中的逻辑位置，例如 &lt;code&gt;/articles/category1/example&lt;/code&gt;。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;_map.toml&lt;/code&gt; 引用路径、Hugo &lt;code&gt;.Path&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;发布网址&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;用户访问页面的地址，例如 &lt;code&gt;/zh/p/example-product/&lt;/code&gt;。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;url&lt;/code&gt;、&lt;code&gt;.RelPermalink&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;文章浏览来源&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;用户进入文章时所经的栏目路径，用于呈现该次浏览的导航。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;网址中的 &lt;code&gt;from&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;导航排序状态&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;浏览路径中各栏目及主列表各自采用的排序方式，随网址保留，不传给子栏目。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;网址中的 &lt;code&gt;sorts&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;章节锚点&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;指向正文某一标题或元素的位置标识。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;元素 &lt;code&gt;id&lt;/code&gt;、&lt;code&gt;#标题ID&lt;/code&gt;、&lt;code&gt;anchor&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;共享导航片段&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;构建时生成、由浏览器加载并填入面包屑列的 HTML 内容。&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;/site/navigation/*.txt&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;描述内容组织和浏览方式时使用“分类”；指定某个内容节点及其配置时使用“栏目”。例如：“按用途分类，将文章引用到工具栏目。”&lt;/p&gt;</description></item><item><title>01 开始使用</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/getting-started/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/getting-started/</guid><description>&lt;p&gt;首次使用按本页取得站点、准备工具并完成本地预览，再按&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/site-configuration/"&gt;第二篇教程&lt;/a&gt;设置自己的站点。网站内容与配置由你维护；Banyan 主题提供页面布局，配套 Skill 提供本地工具和检查命令。&lt;/p&gt;&#10;&lt;h2 id="安装前"&gt;安装前&lt;/h2&gt;&#10;&lt;p&gt;目前正在准备首次发布。发布标签可用前，可以使用当前仓库作本地预览；远程 Module 安装须等标签发布。&lt;/p&gt;&#10;&lt;p&gt;支持 Windows x64、Linux x64 和 macOS x64/ARM64。首次运行会复用兼容的已有工具，并下载缺少的工具。不需要另在站点根目录执行 &lt;code&gt;npm install&lt;/code&gt;。主题要求 Hugo 0.168.0 或更新版本，Skill 会准备匹配工具。Linux 需有 sh、基础系统工具、curl、tar、sha256sum；macOS 使用系统自带工具。Git 等工具缺少时会下载到本地目录，无需 Python、Homebrew 或 Xcode。&lt;/p&gt;&#10;&lt;h2 id="取得站点"&gt;取得站点&lt;/h2&gt;&#10;&lt;ol&gt;&#10;&lt;li&gt;在&lt;a href="https://github.com/SwawHQ/banyan/releases"&gt;项目 Releases&lt;/a&gt;选择版本，下载 &lt;strong&gt;Source code (zip)&lt;/strong&gt;。尚无发布版本时，在&lt;a href="https://github.com/SwawHQ/banyan"&gt;仓库首页&lt;/a&gt;选择 &lt;strong&gt;Code → Download ZIP&lt;/strong&gt;，取得当前开发版。&lt;/li&gt;&#10;&lt;li&gt;完整解压到自己的站点目录。确认其中有 &lt;code&gt;hugo.toml&lt;/code&gt;、&lt;code&gt;go.mod&lt;/code&gt;、&lt;code&gt;module/&lt;/code&gt;、&lt;code&gt;content/&lt;/code&gt;、&lt;code&gt;assets/&lt;/code&gt; 和 &lt;code&gt;.agents/&lt;/code&gt;，不要只取 &lt;code&gt;module/&lt;/code&gt;。&lt;/li&gt;&#10;&lt;li&gt;在包含 &lt;code&gt;hugo.toml&lt;/code&gt; 的目录打开 PowerShell。后面的命令都从这里运行。&lt;/li&gt;&#10;&lt;/ol&gt;&#10;&lt;p&gt;完整源码包通过 &lt;code&gt;go.mod&lt;/code&gt; 中的本地替换使用随包附带的 &lt;code&gt;module/&lt;/code&gt;，因此预览时要保留该目录。以后改用已发布的 Module 时，再按下方“调整版本”处理。&lt;/p&gt;&#10;&lt;p&gt;先运行一次：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-powershell" data-lang="powershell"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="kd"&gt;function&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nb"&gt;swban&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&lt;/span&gt; &lt;span class="p"&gt;.\&lt;/span&gt;&lt;span class="n"&gt;swban&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="py"&gt;cmd&lt;/span&gt; &lt;span class="nv"&gt;@args&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="c"&gt;#在本终端定义命令简称&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="n"&gt;swban&lt;/span&gt; &lt;span class="n"&gt;base&lt;/span&gt;&lt;span class="p"&gt;/&lt;/span&gt;&lt;span class="n"&gt;hugo&lt;/span&gt; &lt;span class="n"&gt;version&lt;/span&gt; &lt;span class="c"&gt;#准备工具并显示 Hugo 版本&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="n"&gt;swban&lt;/span&gt; &lt;span class="n"&gt;base&lt;/span&gt;&lt;span class="p"&gt;/&lt;/span&gt;&lt;span class="n"&gt;packages&lt;/span&gt;&lt;span class="p"&gt;/&lt;/span&gt;&lt;span class="n"&gt;ensure&lt;/span&gt; &lt;span class="c"&gt;#准备 Skill 核心依赖&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="n"&gt;swban&lt;/span&gt; &lt;span class="n"&gt;doctor&lt;/span&gt; &lt;span class="c"&gt;#检查工具、主题和 Skill&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;&lt;code&gt;swban&lt;/code&gt; 是上面定义的 PowerShell 函数，不是自动加入 PATH 的命令。新开终端时重新定义，或使用完整的 &lt;code&gt;.\.agents\skills\swaw-banyan\swban.cmd&lt;/code&gt; 路径。若命令报错，先按提示处理，再继续。&lt;/p&gt;</description></item><item><title>01 本地开发</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/local-development/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/local-development/</guid><description>&lt;h2 id="仓库结构"&gt;仓库结构&lt;/h2&gt;&#10;&lt;p&gt;Banyan 仓库维护主题、Skill、源码测试、参考站点、使用指南、开发资料和版本说明。&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;banyan/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── hugo.toml, go.mod #最小演示配置&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/articles/ #正文、文章分类、文档和版本说明&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/articles/docs-guide/ #使用指南&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/articles/docs-dev/ #开发资料&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/articles/changelog/ #主题和 Skill 版本说明&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/articles-all/ #文章汇总&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/products/ #产品分类与一份引用&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/products-all/ #产品汇总&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/{appearance,language,my,rss}/ #站点自有设置和说明页&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── assets/site/ #站点资源和交付配置&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── assets/i18n/ #由项目挂载的界面字典&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/powered-by/ #版本信息与预取诊断&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/_res/ #离线页和首页艺术包&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── module/ #布局、脚本和样式，不含站点内容&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── .agents/skills/swaw-banyan/ #本地工具和通用检查任务&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;└── tests/ #主题和工具源码测试&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Banyan 根 &lt;code&gt;go.mod&lt;/code&gt; 使用 &lt;code&gt;replace ... =&amp;gt; ./module&lt;/code&gt;，直接读取随仓库提供的主题源码，无需先发布 Module。其他站点可用本地 &lt;code&gt;replace&lt;/code&gt; 指向这份源码。&#10;站点定制留在各站点根目录，可复用主题行为放入 Banyan 的 &lt;code&gt;module/&lt;/code&gt;。&#10;独立站点发布时通常固定 Module 版本。完整仓库随附的 &lt;code&gt;./module&lt;/code&gt; 可参与托管构建；指向仓库外目录的本地替换路径则不可用。&lt;/p&gt;</description></item><item><title>02 设置自己的站点</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/site-configuration/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/site-configuration/</guid><description>&lt;h2 id="根配置"&gt;根配置&lt;/h2&gt;&#10;&lt;p&gt;本页在完整参考站点上修改配置。安装和预览命令见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/getting-started/"&gt;开始使用&lt;/a&gt;。示例只展示相关字段：在已有表中修改对应项，不要把整段追加到文件末尾。&lt;/p&gt;&#10;&lt;p&gt;在 &lt;code&gt;hugo.toml&lt;/code&gt; 开头修改正式网址：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-toml" data-lang="toml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;baseURL&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;https://example.com/&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;把示例域名换成自己的完整网址；如果部署在子目录中，连同子目录一起填写，例如 &lt;code&gt;https://example.com/blog/&lt;/code&gt;。它影响站点地图、订阅和规范地址。本地预览仍使用终端显示的本机网址。&lt;/p&gt;&#10;&lt;p&gt;初次配置时保留其余构建设置，尤其是：&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;设置&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;保留它的原因&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;minify.disableJS = true&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;避免压缩改变脚本后，浏览器因 CSP 拒绝执行&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;module.mounts&lt;/code&gt; 中的界面字典挂载&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;让界面使用站点的 &lt;code&gt;assets/i18n/&lt;/code&gt; 字典&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;cascade&lt;/code&gt; 中的 &lt;code&gt;build.publishResources = false&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;避免自动发布未使用的页面包文件，包括 &lt;code&gt;_map.toml&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;printPathWarnings&lt;/code&gt;、&lt;code&gt;panicOnWarning&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;在页面发布网址冲突时停止构建&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;文章网址与栏目目录见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/directories/"&gt;目录与引用&lt;/a&gt;，索引开关见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/discovery/"&gt;站点发现&lt;/a&gt;，部署步骤见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/deploying/"&gt;首次部署&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="站点说明与语言"&gt;站点说明与语言&lt;/h2&gt;&#10;&lt;p&gt;先编辑首页。参考站的 &lt;code&gt;content/_index.md&lt;/code&gt; 是英文首页，&lt;code&gt;content/_index.zh.md&lt;/code&gt; 是中文首页，&lt;code&gt;content/_index.ar.md&lt;/code&gt; 是阿拉伯文首页。例如，在中文首页修改已有字段：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;title&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;我的站点&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;description&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;介绍本站提供的内容。&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;&lt;code&gt;title&lt;/code&gt; 用作站名；&lt;code&gt;linkTitle&lt;/code&gt; 可单独设置导航文字。参考首页还设有 &lt;code&gt;params.browser_title&lt;/code&gt;，它会覆盖浏览器标签标题，应一并修改或删除。各篇文章的 &lt;code&gt;description&lt;/code&gt; 可覆盖首页提供的默认说明。&lt;/p&gt;&#10;&lt;p&gt;首页可见的风场文字来自它引用的艺术包，不是首页的 &lt;code&gt;title&lt;/code&gt;。修改步骤见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/appearance-customization/#%e9%a6%96%e9%a1%b5%e4%bf%a1%e5%8f%b7"&gt;首页定制&lt;/a&gt;；想先用简单文字首页，可切换到&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/appearance-customization/#%e6%9c%80%e5%b0%8f%e9%a6%96%e9%a1%b5%e8%89%ba%e6%9c%af%e5%8c%85"&gt;最小首页艺术包&lt;/a&gt;。&lt;/p&gt;&#10;&lt;p&gt;语言在 &lt;code&gt;hugo.toml&lt;/code&gt; 的 &lt;code&gt;[languages]&lt;/code&gt; 中设置：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-toml" data-lang="toml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;languages&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;en&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;label&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;English&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;en&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;locale&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;en-US&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;en&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;weight&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;zh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;label&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;中文&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;zh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;locale&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;zh-Hans&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;zh&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;weight&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;&lt;code&gt;label&lt;/code&gt; 是语言名称，&lt;code&gt;weight&lt;/code&gt; 控制排列顺序；根配置的 &lt;code&gt;defaultContentLanguage&lt;/code&gt; 决定默认语言。它不会随排列顺序改变。&lt;code&gt;defaultContentLanguageInSubdir&lt;/code&gt; 决定默认语言是否也放在语言子目录中，调整后检查原有网址。&lt;/p&gt;&#10;&lt;p&gt;暂时不提供某种语言时，可在文件顶部、任何 TOML 表之前设置：&lt;/p&gt;</description></item><item><title>02 项目结构与源码入口</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/partial-architecture/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/partial-architecture/</guid><description>&lt;h2 id="页面入口"&gt;页面入口&lt;/h2&gt;&#10;&lt;p&gt;以下路径相对 &lt;code&gt;module/&lt;/code&gt;。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;目录或入口&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;职责&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/baseof.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;页面整体装配&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/page-*.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;内容选择的页面布局&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;入口私有模板、功能模板与系统机制&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_shortcodes/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;正文短代码&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_markup/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Markdown 渲染&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/rss.xml&lt;/code&gt;、&lt;code&gt;sitemap.xml&lt;/code&gt;、&lt;code&gt;home.llms.txt&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;订阅与站点发现输出&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/&lt;/code&gt;、&lt;code&gt;assets/css/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;浏览器行为与样式&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;&lt;code&gt;page-*&lt;/code&gt; 是布局命名，不表示 Hugo 的 page 类型。集合布局用于普通栏目；首页另支持汇总图片墙。当前没有 taxonomy 和 term 的列表布局。配置方法见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/collection-lists/"&gt;列表与产品声明&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="partial-所有权"&gt;Partial 所有权&lt;/h2&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;目录（相对 &lt;code&gt;layouts/_partials/&lt;/code&gt;）&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;职责&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;entry-baseof/&lt;/code&gt;、&lt;code&gt;entry-page-home/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;入口独有的装配与检查&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-browse/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;内容成员、引用、列表、图片墙和导航&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-document/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;正文、元信息、章节与文章结构化数据&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-preferences/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;语言和外观选项&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-prefetch-debug/&lt;/code&gt;、&lt;code&gt;feature-site-status/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;诊断与状态显示&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-ui/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;公共列表、图标、控件与页面样式&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-assets/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;资源定位、处理、构建与发布&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-metadata/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;SEO、分享信息和 Agent 索引&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-delivery/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;SW、预取、缓存与部署配置&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-build/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;站点构建版本与时间&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;h2 id="依赖方向"&gt;依赖方向&lt;/h2&gt;&#10;&lt;p&gt;入口组合功能与系统模块；功能模块可以使用系统模块，系统模块不反向读取功能状态。跨功能依赖保持明确、单向，例如文章元信息读取内容归属。&lt;/p&gt;&#10;&lt;p&gt;公共 UI 接收功能模块生成的字段与链接，不负责发现成员。资源构建接收调用者指定的资源，不自行读取浏览来源。SEO 消费构建期模型，不以浏览器来源作为规范路径。&lt;/p&gt;&#10;&lt;p&gt;新增代码先放在所属入口或功能附近，出现实际复用后再提取。不要为目录对称增加空层或转发模板。&lt;/p&gt;&#10;&lt;h2 id="功能内部边界"&gt;功能内部边界&lt;/h2&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;重要约定&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;源码入口（相对 &lt;code&gt;layouts/_partials/&lt;/code&gt;）&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;列表、计数、RSS 与反向引用共用成员索引&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-browse/directory/index.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;引用不创建页面，不改变 Parent 与正文网址&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-browse/directory/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;结构路径与浏览来源分别维护&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-browse/navigation/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;资源定位与发布分开，衍生图不必额外发布源图&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-assets/resolve-page.html&lt;/code&gt;、&lt;code&gt;publish-page.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;共享列表只装配公共控件&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-ui/list/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;内联脚本与 CSP 使用同一份最终正文&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;entry-baseof/inline-scripts.html&lt;/code&gt;、&lt;code&gt;system-delivery/deployment/csp-value.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;站点发现使用实际发布页面；引用不会产生新的规范地址。LLMS 可以把同一正文列入真实栏目和引用栏目，规则见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/discovery/"&gt;站点发现&lt;/a&gt;。&lt;/p&gt;</description></item><item><title>内容 · 列表、图片墙与产品</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/collection-lists/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/collection-lists/</guid><description>&lt;p&gt;页面的 &lt;code&gt;layout&lt;/code&gt; 选择列表字段和行为。普通目录的成员来自实际文章和本目录 &lt;code&gt;_map.toml&lt;/code&gt; 的引用。选择页的选项由对应布局提供。自定义字段放在 &lt;code&gt;params&lt;/code&gt;，继承默认值放在 &lt;code&gt;cascade.params&lt;/code&gt;。&lt;/p&gt;&#10;&lt;h2 id="在哪里改列表"&gt;在哪里改列表&lt;/h2&gt;&#10;&lt;p&gt;在栏目的 &lt;code&gt;_index.&amp;lt;lang&amp;gt;.md&lt;/code&gt; 中选择 &lt;code&gt;layout&lt;/code&gt;。以下路径使用 Banyan 参考站的命名；站点可以自行命名栏目。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;用途&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;layout&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;收录范围&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;普通栏目&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;page-collection-directory&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;直属子栏目、文章和引用&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;名称列表&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;page-collection-directory-name-only&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;同上，只显示名称&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;产品列表&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;page-collection-products&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;直属子项和引用，显示产品字段&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;文章汇总&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;page-collection-directory-all&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;params.aggregate&lt;/code&gt; 指定栏目及下级文章和引用&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;产品汇总&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;page-collection-products-all&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;同上，显示产品字段&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;例如，在 &lt;code&gt;content/products/examples/_index.zh.md&lt;/code&gt; 中选择产品列表：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;layout&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;page-collection-products&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;列表仍包含原有子项，产品布局显示名称、更新时间、价格，默认按更新时间倒序；没有 &lt;code&gt;params.offer&lt;/code&gt; 的文章显示价格 &lt;code&gt;—&lt;/code&gt;。&lt;code&gt;page-collection-directory-all&lt;/code&gt; 显示名称、更新时间和大小，且需指定 &lt;code&gt;params.aggregate&lt;/code&gt;；&lt;code&gt;page-collection-directory&lt;/code&gt; 显示名称、更新时间、数量／大小；&lt;code&gt;page-collection-directory-name-only&lt;/code&gt; 只显示带图标的名称。布局可沿内容祖先的 &lt;code&gt;cascade&lt;/code&gt; 继承。普通文章使用 &lt;code&gt;page-article-rss&lt;/code&gt; 或 &lt;code&gt;page-article-norss&lt;/code&gt;，不会因栏目布局变成列表。&lt;/p&gt;&#10;&lt;p&gt;新增普通列表目录时使用 &lt;code&gt;_index.&amp;lt;lang&amp;gt;.md&lt;/code&gt;，声明 &lt;code&gt;layout: page-collection-directory&lt;/code&gt; 和需要的 &lt;code&gt;params.slots: [breadcrumb]&lt;/code&gt;；位于已有目录下时可继承布局和区域声明。正文只写介绍，列表显示在介绍之前。单篇文章使用 &lt;code&gt;name/index.&amp;lt;lang&amp;gt;.md&lt;/code&gt; 叶子包。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;params.aggregate&lt;/code&gt; 只用于名称以 &lt;code&gt;-all&lt;/code&gt; 结尾的汇总布局，指向一个普通 section 根。普通目录页无需写 &lt;code&gt;aggregate&lt;/code&gt;。所有页面直接在站点根 &lt;code&gt;content/&lt;/code&gt; 维护；各语言维护各自的页面字段。&lt;/p&gt;&#10;&lt;h2 id="普通栏目图片墙"&gt;普通栏目图片墙&lt;/h2&gt;&#10;&lt;p&gt;普通栏目的 &lt;code&gt;_index*.md&lt;/code&gt; 使用 &lt;code&gt;page-collection-wall&lt;/code&gt;，显示直属子栏目、文章及引用。目录在前，文章在后；文章按发布日期倒序。它与下方汇总图片墙共用 &lt;code&gt;params.wall&lt;/code&gt; 配置。&lt;/p&gt;</description></item><item><title>内容 · 栏目与引用</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/directories/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/directories/</guid><description>&lt;h2 id="用目录组织正文"&gt;用目录组织正文&lt;/h2&gt;&#10;&lt;p&gt;分类通过栏目层级和文章引用实现，栏目名称由站点定义。Banyan 最小演示用 &lt;code&gt;articles&lt;/code&gt;、&lt;code&gt;articles-all&lt;/code&gt; 展示文章分类与全部列表，&#10;用 &lt;code&gt;products&lt;/code&gt;、&lt;code&gt;products-all&lt;/code&gt; 展示产品分类与全部列表。这些目录名可以按本站需要修改。&lt;/p&gt;&#10;&lt;p&gt;正文放在所属目录中，栏目列表直接使用这些文件。需要把同一篇文章列入其他栏目时，&#10;在目标栏目放入 &lt;code&gt;_map.toml&lt;/code&gt;，添加栏目文章引用。&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;content/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├─ articles/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ ├─ _index.md&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └─ category1/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ ├─ _index.md&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └─ example/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └─ index.md&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├─ articles-all/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └─ _index.md&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├─ products/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ ├─ _index.md&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └─ examples/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ ├─ _index.md&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;│ └─ _map.toml&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;└─ products-all/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; └─ _index.md&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;示例省略同路径的中文译文。有子文章的栏目使用 &lt;code&gt;_index.&amp;lt;lang&amp;gt;.md&lt;/code&gt;，其中的标题、&#10;介绍和正文属于该栏目。单篇文章统一使用 &lt;code&gt;name/index.&amp;lt;lang&amp;gt;.md&lt;/code&gt; 叶子包，&#10;文章资源放在同一目录。&lt;code&gt;index.&amp;lt;lang&amp;gt;.md&lt;/code&gt; 不用于容纳下级文章的栏目。&#10;默认语言文件可以省略语言后缀。&lt;/p&gt;&#10;&lt;p&gt;文章模板由站点根 &lt;code&gt;archetypes/banyan.md&lt;/code&gt; 维护，Module 和传统主题目录不提供。&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban base/hugo new content --kind banyan articles/my-post/index.zh.md #新建中文文章&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;生成后编辑标题、说明和正文，发布前将 &lt;code&gt;draft&lt;/code&gt; 改为 &lt;code&gt;false&lt;/code&gt;。完整操作见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/getting-started/#%e6%b7%bb%e5%8a%a0%e7%ac%ac%e4%b8%80%e7%af%87%e6%96%87%e7%ab%a0"&gt;添加第一篇文章&lt;/a&gt;。栏目布局和文章布局由上级 &lt;code&gt;cascade&lt;/code&gt; 继承，无须为每篇文章再写分类字段。&#10;列表配置见 &lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/collection-lists/"&gt;列表与产品声明&lt;/a&gt;。&lt;/p&gt;</description></item><item><title>发布 · 主题版本</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/releasing/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/releasing/</guid><description>&lt;h2 id="变更记录"&gt;变更记录&lt;/h2&gt;&#10;&lt;p&gt;在 Banyan 仓库的 &lt;code&gt;content/articles/changelog/unreleased/index.md&lt;/code&gt;&#10;及其中文译文记录用户可见的变化、配置要求和实际修复。&#10;合并同类条目，不记录内部重构、测试细节或仅属于消费站点的变化。首次发布说明主要能力、使用要求和已知限制，不列开发期旧格式的迁移历史。后续版本只记录相对上一发布版的用户变化；需要操作时，说明受影响配置和处理步骤。&lt;/p&gt;&#10;&lt;p&gt;发布时将该 bundle 移至 Banyan 仓库的&#10;&lt;code&gt;content/articles/changelog/vX.Y.Z/&lt;/code&gt;，把 &lt;code&gt;title&lt;/code&gt; 设为 &lt;code&gt;vX.Y.Z&lt;/code&gt;、&#10;&lt;code&gt;url&lt;/code&gt; 设为 &lt;code&gt;p/vX.Y.Z/&lt;/code&gt;，把 &lt;code&gt;date&lt;/code&gt; 和 &lt;code&gt;lastmod&lt;/code&gt; 设为发布日期。&#10;新建 unreleased bundle，将 &lt;code&gt;date&lt;/code&gt; 和 &lt;code&gt;lastmod&lt;/code&gt; 设为新页面的首次发布日期；“未发布”指软件版本状态。集合布局会自动列出版本页面。&#10;版本说明发布在 &lt;code&gt;https://banyan.swaw.com/p/vX.Y.Z/&lt;/code&gt;，中文在&#10;&lt;code&gt;https://banyan.swaw.com/zh/p/vX.Y.Z/&lt;/code&gt;；内容目录移动不改变这些正文网址。&lt;/p&gt;&#10;&lt;h2 id="配套标签"&gt;配套标签&lt;/h2&gt;&#10;&lt;p&gt;在 Banyan 仓库更新 Skill 的 &lt;code&gt;metadata.version&lt;/code&gt; 和 &lt;code&gt;module/theme.toml&lt;/code&gt; 的 &lt;code&gt;version&lt;/code&gt;，&#10;使用同一本次版本号，将源码、文档和版本说明提交到同一个 Banyan 提交。&#10;两个发布标签都创建在 Banyan 仓库，指向该提交。&lt;/p&gt;&#10;&lt;p&gt;进入 Banyan 仓库根目录后执行。命令从当前提交读取版本，校验 Theme、Skill&#10;版本和 Module 标识，再向 &lt;code&gt;origin&lt;/code&gt; 原子发布配套标签：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban deploy/release/tag --check #校验并查看标签计划&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban deploy/release/tag #原子发布两个版本标签&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;命令读取已提交的版本文件。运行前提交本次源码和文档，并用 &lt;code&gt;--check&lt;/code&gt; 核对版本与目标仓库。&lt;/p&gt;&#10;&lt;p&gt;以版本 &lt;code&gt;0.1.0&lt;/code&gt; 为例，&lt;code&gt;v0.1.0&lt;/code&gt; 用于项目发布和提取 Skill；&#10;&lt;code&gt;module/v0.1.0&lt;/code&gt; 供 Go 将子目录 Module 识别为 &lt;code&gt;v0.1.0&lt;/code&gt;。&#10;因为 Module 根目录是 &lt;code&gt;module/&lt;/code&gt;，仅有项目标签不能提供该 Module 的语义版本。&#10;这是 &lt;a href="https://go.dev/ref/mod#vcs-version"&gt;Go 的子目录 Module 标签规则&lt;/a&gt;。&#10;GitHub Release 使用 &lt;code&gt;v0.1.0&lt;/code&gt;，无需再为 &lt;code&gt;module/v0.1.0&lt;/code&gt; 创建 Release。&#10;若附带 Skill ZIP，包含 Skill 目录和许可证，排除 &lt;code&gt;.tools&lt;/code&gt;、&lt;code&gt;node_modules&lt;/code&gt; 和缓存。&lt;/p&gt;</description></item><item><title>发布 · 站点发现与来源链接</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/discovery/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/discovery/</guid><description>&lt;h2 id="结构化数据"&gt;结构化数据&lt;/h2&gt;&#10;&lt;p&gt;页面使用 JSON-LD 向机器提供结构化数据。Schema.org 定义类型和字段：&#10;站点使用 &lt;code&gt;WebSite&lt;/code&gt;，文章使用 &lt;code&gt;BlogPosting&lt;/code&gt;，面包屑使用 &lt;code&gt;BreadcrumbList&lt;/code&gt;，集合列表使用 &lt;code&gt;ItemList&lt;/code&gt;。&#10;这些数据由模板随 HTML 生成。概念见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/glossary/#%e7%bb%93%e6%9e%84%e5%8c%96%e6%95%b0%e6%8d%ae"&gt;项目术语表&lt;/a&gt;，&#10;文章和面包屑数据的装配见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/layout-slots/"&gt;页面区域与布局&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="rss-订阅"&gt;RSS 订阅&lt;/h2&gt;&#10;&lt;p&gt;在 &lt;code&gt;content/rss/index*.md&lt;/code&gt; 中维护订阅说明，正文调用 &lt;code&gt;{{&amp;lt; rss-link &amp;gt;}}&lt;/code&gt; 显示当前语言的订阅地址。&lt;/p&gt;&#10;&lt;p&gt;使用前在 &lt;code&gt;[outputs].home&lt;/code&gt; 启用 RSS；删除 RSS 说明页不会关闭订阅输出。&lt;/p&gt;&#10;&lt;p&gt;RSS 页面按“全部文章 + 分类订阅”组织：全站地址使用 &lt;code&gt;rss-link&lt;/code&gt; 读取实际输出；分类部分说明各栏目订阅地址。示例通过 &lt;code&gt;site-root&lt;/code&gt; 输出当前语言首页的绝对网址，自动保留部署子路径和语言前缀，其余分类路径以代码展示。分类是否提供 RSS 由其输出配置决定；普通文章默认不单独发布 RSS。&lt;/p&gt;&#10;&lt;p&gt;栏目 RSS 与目录计数、汇总列表共用递归成员，包含子栏目的真实文章和 &lt;code&gt;_map.toml&lt;/code&gt; 引用。&#10;同一正文在一个 feed 中只出现一次，链接始终指向原文。RSS 只收录布局为 &lt;code&gt;page-article-rss&lt;/code&gt; 的文章。首页 RSS 使用当前语言可列出的文章；&#10;产品栏目使用相同规则；不同栏目的 RSS 可以收录同一篇文章。输出由 &lt;code&gt;[outputs]&lt;/code&gt; 控制，条数使用 &lt;code&gt;[services.rss].limit&lt;/code&gt;。&lt;/p&gt;&#10;&lt;h2 id="sitemap"&gt;Sitemap&lt;/h2&gt;&#10;&lt;p&gt;Sitemap 收录已渲染且可索引的 HTML 页面，包括 &lt;code&gt;build.list: local&lt;/code&gt; 和&#10;&lt;code&gt;build.list: never&lt;/code&gt; 页面。页面 front matter 可用以下设置排除收录：&lt;/p&gt;</description></item><item><title>外观 · 应用名称与图标</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/web-app/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/web-app/</guid><description>&lt;p&gt;Manifest 是浏览器读取的应用清单，用于安装后的应用名称、启动地址和图标。它与 SW 缓存分别配置；关闭 SW 时仍需保留应用清单和图标文件。&lt;/p&gt;&#10;&lt;h2 id="站点图标"&gt;站点图标&lt;/h2&gt;&#10;&lt;p&gt;在 &lt;code&gt;assets/site/&lt;/code&gt; 中替换下列文件，保留原文件名：&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;源文件&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;用途&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;favicon.ico&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;固定地址的浏览器图标&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;favicon.link.svg&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;页面优先使用的 SVG 图标&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;favicon.link.ico&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;没有上述 SVG 时使用的 ICO 图标&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;icon-180.png&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;180 × 180 的 Apple touch 图标&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;icon-192.png&lt;/code&gt;、&lt;code&gt;icon-256.png&lt;/code&gt;、&lt;code&gt;icon-512.png&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;对应尺寸的安装图标&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;参考站使用 SVG 页面图标，并提供表中的浏览器图标和安装图标。替换其中实际使用的文件，再检查浅色、深色和浏览器标签上的显示。SVG 可使用原有尺寸或只声明 &lt;code&gt;viewBox&lt;/code&gt;。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;favicon.link.svg&lt;/code&gt; 与 &lt;code&gt;favicon.link.ico&lt;/code&gt; 同时存在时使用 SVG；如果想改用 ICO，需要移除对应 SVG。&lt;code&gt;favicon.ico&lt;/code&gt; 单独发布，不能只替换它就认为页面标签图标也已改变。&lt;/p&gt;&#10;&lt;p&gt;安装图标与文章分享图分别设置，分享图见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/discovery/#%e5%88%86%e4%ba%ab%e5%9b%be%e7%89%87"&gt;站点发现&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="manifest"&gt;Manifest&lt;/h2&gt;&#10;&lt;p&gt;打开 &lt;code&gt;assets/site/manifest.webmanifest.tmpl&lt;/code&gt;，修改已有值：&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;内容&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;修改位置&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;应用名称&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;默认语言首页的 &lt;code&gt;title&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;启动网址&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;模板中的 &lt;code&gt;start_url&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;应用范围&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;模板中的 &lt;code&gt;scope&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;应用标识&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;模板中的 &lt;code&gt;id&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;启动背景和主题颜色&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;模板中的 &lt;code&gt;background_color&lt;/code&gt;、&lt;code&gt;theme_color&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;参考模板自动根据 &lt;code&gt;baseURL&lt;/code&gt; 设置应用标识、启动网址和范围，部署在子目录时无需另改这三项。需要自定义启动页或范围时，再修改对应模板值。&lt;/p&gt;</description></item><item><title>外观 · 页面区域与导航</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/layout-slots/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/layout-slots/</guid><description>&lt;h2 id="第一列入口"&gt;第一列入口&lt;/h2&gt;&#10;&lt;p&gt;根导航列显示当前语言的首页和已发布的直属页面。新增入口时，在 &lt;code&gt;content/&lt;/code&gt; 下创建根栏目或独立页面，并设置名称、顺序和图标：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;title&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;关于&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;weight&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="m"&gt;90&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;params&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;icon&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;{&lt;span class="nt"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;©&amp;#34;&lt;/span&gt;}&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;入口名称优先使用 &lt;code&gt;linkTitle&lt;/code&gt;，未设置时使用 &lt;code&gt;title&lt;/code&gt;；顺序使用入口自身的 &lt;code&gt;weight&lt;/code&gt;，不要向全部文章继承这个值。图标配置见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/collection-lists/#%e6%80%8e%e6%a0%b7%e5%a3%b0%e6%98%8e%e6%9d%a1%e7%9b%ae%e5%9b%be%e6%a0%87"&gt;列表与产品声明&lt;/a&gt;。&lt;/p&gt;&#10;&lt;p&gt;内部页面可用 &lt;code&gt;build.list: never&lt;/code&gt; 隐藏入口。删除根页面也会移除对应入口。首页在 &lt;code&gt;content/_index*.md&lt;/code&gt; 中配置；&lt;code&gt;params.show_navigation&lt;/code&gt; 控制首页是否显示根导航列。&lt;/p&gt;&#10;&lt;p&gt;从引用栏目进入文章时，导航显示该次来源；直接打开文章时，显示文章默认归属。正文仍使用同一发布网址，见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/directories/"&gt;目录与引用&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="站点说明页与外部链接"&gt;站点说明页与外部链接&lt;/h2&gt;&#10;&lt;p&gt;关于、GitHub 等说明页使用 &lt;code&gt;page-article-norss&lt;/code&gt;，避免进入文章 RSS。参考文件在 &lt;code&gt;content/about/&lt;/code&gt; 和 &lt;code&gt;content/github/&lt;/code&gt;；修改各语言正文和链接即可。&lt;/p&gt;&#10;&lt;p&gt;外部目标放在说明页正文中。需要在新标签打开时使用短代码：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;{{&amp;lt; new-tab href=&amp;#34;https://example.com/&amp;#34; &amp;gt;}}访问网站{{&amp;lt; /new-tab &amp;gt;}}&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;正文内的小图标可用 &lt;code&gt;asset&lt;/code&gt; 短代码，并设置 &lt;code&gt;class=&amp;quot;md-inline-image&amp;quot;&lt;/code&gt;。例如，页面包中有 &lt;code&gt;badge.webp&lt;/code&gt; 时：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;{{&amp;lt; asset src=&amp;#34;badge.webp&amp;#34; alt=&amp;#34;图标说明&amp;#34; class=&amp;#34;md-inline-image&amp;#34; width=&amp;#34;16&amp;#34; height=&amp;#34;16&amp;#34; &amp;gt;}}&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;RSS 说明页与订阅开关见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/discovery/#rss-%e8%ae%a2%e9%98%85"&gt;RSS 订阅&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="支持的-slots"&gt;支持的 slots&lt;/h2&gt;&#10;&lt;p&gt;页面的 &lt;code&gt;params.slots&lt;/code&gt; 选择需要的区域。省略名称会关闭对应区域，&lt;code&gt;[]&lt;/code&gt; 关闭全部可选区域。根导航列和正文不由此项控制。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;名称&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;开启的内容&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;breadcrumb&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;面包屑列和面包屑结构化数据（BreadcrumbList）&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;meta&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;文章元信息、章节目录和文章结构化数据（BlogPosting）&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;省略 &lt;code&gt;meta&lt;/code&gt; 会同时关闭这三部分。页内“目录与信息”按钮只展开或收起辅助内容，不改变结构化数据输出。&lt;/p&gt;</description></item><item><title>未发布</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/unreleased/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/unreleased/</guid><description>&lt;p&gt;本项目正在准备首次发布。以下说明首版交付范围；发布标签可用后，再按&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/getting-started/"&gt;开始使用&lt;/a&gt;安装。&lt;/p&gt;&#10;&lt;h2 id="主要能力"&gt;主要能力&lt;/h2&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&#10;&lt;p&gt;&lt;code&gt;swban dev&lt;/code&gt; 启动含草稿的开发服，首次渲染后建立搜索索引，使用独立临时输出并在退出后清理。&lt;code&gt;dev/lan&lt;/code&gt; 支持局域网预览，&lt;code&gt;dev/pagefind.off&lt;/code&gt; 可跳过索引；追加参数传给 Hugo，启动时显示实际命令并保留工具输出。搜索索引通过重启开发服更新。&lt;/p&gt;&#10;&lt;/li&gt;&#10;&lt;li&gt;&#10;&lt;p&gt;提供独立搜索页，按当前语言实时搜索正文；结果使用正文列宽和加粗标题，整条结果可点击，并复用主题预选效果。搜索页支持 RSS 范围、HTML 文件匹配或目录数组，并用已有 HTML 选择器限定正文，无需添加 Pagefind 专用属性。根目录命令入口支持 &lt;code&gt;swban build&lt;/code&gt;，一键生成站点和 Pagefind 索引。&lt;/p&gt;&#10;&lt;/li&gt;&#10;&lt;li&gt;&#10;&lt;p&gt;构建拒绝覆盖源码目录及自定义挂载目录；无搜索页或 RSS 收录为空时不准备 Pagefind。空 RSS 可正常构建，缺少当前语言索引时显示无结果，搜索摘要正确显示转义字符。&lt;/p&gt;&#10;&lt;/li&gt;&#10;&lt;li&gt;&#10;&lt;p&gt;通过 Hugo Module 提供页面布局、脚本和样式，配套 &lt;code&gt;swaw-banyan&lt;/code&gt; Agent Skill 提供本地工具、构建检查和版本维护。浏览器检查支持部署子目录和默认语言子目录，SW 停用检查按实际部署范围执行。&lt;/p&gt;&#10;&lt;/li&gt;&#10;&lt;li&gt;&#10;&lt;p&gt;用栏目和文章引用组织内容。同一正文可以进入多个分类，保留一个发布网址；支持汇总列表和栏目 RSS。共享引用也适用于仅有非默认语言首页的栏目。&lt;/p&gt;&#10;&lt;/li&gt;&#10;&lt;li&gt;&#10;&lt;p&gt;提供目录列表、名称列表、产品列表和图片墙。面包屑列保留文章浏览来源，各列可独立排序；栏目可配置默认排序字段与升降序，进入子栏目时不继承父栏排序。&lt;/p&gt;&#10;&lt;/li&gt;&#10;&lt;li&gt;&#10;&lt;p&gt;支持多语言、从右向左排版、浅色与深色外观，以及自定义配色和首页艺术包。参考站提供英语、简体中文和阿拉伯语。&lt;/p&gt;&#10;&lt;/li&gt;&#10;&lt;li&gt;&#10;&lt;p&gt;支持 Web App Manifest、可选的 SW 缓存与离线页面、页面预取和原生预渲染。Manifest 地址和 SW 作用范围跟随部署子目录，SVG 浏览器图标支持原有尺寸及仅含 &lt;code&gt;viewBox&lt;/code&gt; 的图形。Powered by 页面提供版本信息与诊断入口。&lt;/p&gt;&#10;&lt;/li&gt;&#10;&lt;li&gt;&#10;&lt;p&gt;生成站点地图、RSS、&lt;code&gt;llms.txt&lt;/code&gt;、社交分享信息和结构化数据。&lt;/p&gt;&#10;&lt;/li&gt;&#10;&lt;li&gt;&#10;&lt;p&gt;从站点交付配置生成 Cloudflare Pages 或 EdgeOne Makers 的部署配置，并生成 CSP 与脚本完整性信息。Skill 提供内容、产物、HTTP 和浏览器检查。EdgeOne 配置只包含交付规则，构建命令和工具版本在平台设置；Skill 按平台分别提供 Git 构建和产物上传指引。&lt;/p&gt;&#10;&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="使用要求"&gt;使用要求&lt;/h2&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;命令帮助改用 &lt;code&gt;help.en.txt&lt;/code&gt; 和 &lt;code&gt;help.zh.txt&lt;/code&gt;；首行为“用法＋两个空格＋#说明”，后续为正文。冷启动与正常运行读取同一份帮助。&lt;/li&gt;&#10;&lt;li&gt;主题要求 Hugo 0.168.0 或更新版本。Skill 命令行支持 Windows x64、Linux x64 和 macOS x64/ARM64；Linux 和 macOS 使用 sh，无需 Python。Git 缺少时会准备便携工具，无需安装系统 Git、Homebrew 或 Xcode。&lt;code&gt;swban build&lt;/code&gt; 会复用兼容的已有工具，并按需下载其他工具。&lt;/li&gt;&#10;&lt;li&gt;新站点从完整根参考站点起步。站点自行维护 &lt;code&gt;hugo.toml&lt;/code&gt;、&lt;code&gt;content/&lt;/code&gt;、&lt;code&gt;archetypes/&lt;/code&gt;、&lt;code&gt;assets/site/&lt;/code&gt; 和 &lt;code&gt;assets/i18n/&lt;/code&gt;；Module 不补充这些文件。&lt;/li&gt;&#10;&lt;li&gt;保留 &lt;code&gt;minify.disableJS = true&lt;/code&gt;，避免 HTML 压缩改变 CSP 授权的脚本正文。&lt;/li&gt;&#10;&lt;li&gt;启用 SW 时，每种已启用语言都要提供 HTML 离线页。参考配置默认关闭 SW 和预取。&lt;/li&gt;&#10;&lt;li&gt;云平台授权和上传由独立的 &lt;a href="https://github.com/SwawHQ/swaw-clouds"&gt;Swaw Clouds&lt;/a&gt; Skill 提供。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="已知限制"&gt;已知限制&lt;/h2&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;账号、支付和评论尚未提供。产品列表只展示产品信息。&lt;/li&gt;&#10;&lt;li&gt;SW 更新不会自动刷新已打开的页面。停用已有 SW 时应使用 &lt;code&gt;disable&lt;/code&gt;；&lt;code&gt;off&lt;/code&gt; 不清理已安装的 SW。&lt;/li&gt;&#10;&lt;li&gt;预取和预渲染受浏览器能力与设置限制。配置档位不保证浏览器一定下载或渲染页面。&lt;/li&gt;&#10;&lt;li&gt;部署目录名不能使用 &lt;code&gt;a%20b&lt;/code&gt; 这类含歧义百分号编码的字面名称；构建会报错。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;配置方法见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/articles/docs-guide/"&gt;使用指南&lt;/a&gt;，源码维护与发布流程见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/articles/docs-dev/"&gt;开发资料&lt;/a&gt;。&lt;/p&gt;</description></item><item><title>检查 · Service Worker 回归</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/service-worker-regression-checklist/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/service-worker-regression-checklist/</guid><description>&lt;p&gt;配置方法见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/delivery/"&gt;交付与缓存&lt;/a&gt;。本文用于修改 SW 实现后的检查，不重复配置表与命令参数。&lt;/p&gt;&#10;&lt;h2 id="源码入口"&gt;源码入口&lt;/h2&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;位置（相对 &lt;code&gt;module/&lt;/code&gt;）&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;职责&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/system-delivery/pwa/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;配置、离线页和程序资源装配&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/pwa/worker-enable.js.tmpl&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;缓存、程序生命周期和站点构建版本&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/pwa/manager-entry.js.tmpl&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;普通页面注册&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/site-status/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Powered by 的程序与内容检查&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/pwa/worker-disable.js&lt;/code&gt;、&lt;code&gt;manager-disable.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;停用与清理&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/pwa/cache-names.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;受管缓存名称&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;h2 id="页面与程序更新"&gt;页面与程序更新&lt;/h2&gt;&#10;&lt;p&gt;普通页面加载完成后注册，预渲染页面在激活后注册。浏览器负责正常程序更新与激活；页面链接、刷新、历史导航和检查按钮不能提前激活 waiting 程序，也不能自动重载页面。&lt;/p&gt;&#10;&lt;p&gt;检查首次安装、存在活动程序时的更新、等待期间的内容更新，以及停用后重新启用。首次安装须取得有效站点构建版本和默认语言离线页；后续更新须保留有效离线回退。安装与激活期间的暂存处理以 worker 源码及生命周期测试为准。&lt;/p&gt;&#10;&lt;h2 id="站点构建版本"&gt;站点构建版本&lt;/h2&gt;&#10;&lt;p&gt;站点构建版本与 SW 程序版本分别变化。只改内容版本时，&lt;code&gt;sw.js&lt;/code&gt; 字节应保持不变。版本 JSON 须与内容一同部署；手动设置 &lt;code&gt;params.build.version&lt;/code&gt; 时，每次内容发布都要更新它。&lt;/p&gt;&#10;&lt;p&gt;达到检查间隔后的首次受管导航应启动后台检查，不等待导航成功，不阻塞导航响应；并发导航共用一次请求。失败时保留原版本。waiting 程序存在时，活动程序仍可检查内容。&lt;/p&gt;&#10;&lt;p&gt;发现新构建版本后，后续请求使用新缓存；已打开页面保持原状。版本切换清理旧版本缓存，保留指纹缓存。旧请求完成时不能重新创建已删除的缓存。&lt;/p&gt;&#10;&lt;h2 id="缓存契约"&gt;缓存契约&lt;/h2&gt;&#10;&lt;p&gt;缓存与 HTTP 响应头分别配置。版本缓存未命中时重新验证 HTTP 缓存，避免旧 HTML 写入新版本缓存。&lt;code&gt;sw.js&lt;/code&gt; 与 &lt;code&gt;sw-version.json&lt;/code&gt; 不进入页面或资源缓存桶。&lt;/p&gt;&#10;&lt;p&gt;首次访问尚未受 SW 控制，页面不追加缓存预热。受控导航缓存 HTML 并预热同源指纹资源。检查已缓存页面离线访问，以及未缓存页面的语言回退。&lt;/p&gt;&#10;&lt;h2 id="disable-模式"&gt;disable 模式&lt;/h2&gt;&#10;&lt;p&gt;&lt;code&gt;disable&lt;/code&gt; 使用独立的清理程序注销本站 SW，删除受管缓存，保留无关缓存。&lt;code&gt;off&lt;/code&gt; 不执行清理。正常更新不能调用停用流程。&lt;/p&gt;&#10;&lt;h2 id="自动化场景"&gt;自动化场景&lt;/h2&gt;&#10;&lt;p&gt;对已启用 SW 的生产构建运行代表检查；停用另行提供启用与停用两份实际构建：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site &amp;lt;build&amp;gt; --updates #检查代表页面与 SW 更新&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/pwa/disable &amp;lt;enabled&amp;gt; --next &amp;lt;disabled&amp;gt; #检查停用&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/http/security &amp;lt;url&amp;gt; #部署后检查响应头&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;准备方式、单项任务、页面要求和报告范围统一见 Skill 的&lt;a href="https://github.com/SwawHQ/banyan/blob/main/.agents/skills/swaw-banyan/references/browser-site.md"&gt;浏览器检查&lt;/a&gt;。两个实际代码版本的比较应使用实际构建对；临时生成的更新构建只用于检查更新机制。&lt;/p&gt;</description></item><item><title>检查 · 浏览器检查</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/browser-regression/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/browser-regression/</guid><description>&lt;p&gt;在目标站点根目录调用已安装的 &lt;code&gt;swban.cmd&lt;/code&gt;。参数、默认值和页面要求以任务的&#10;&lt;code&gt;--help&lt;/code&gt; 为准，检查范围见 Skill 的&lt;a href="https://github.com/SwawHQ/banyan/blob/main/.agents/skills/swaw-banyan/references/browser-site.md"&gt;浏览器说明&lt;/a&gt;。&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban base/browser/ensure #准备 Chromium&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site &amp;lt;build&amp;gt; #检查代表页面&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site &amp;lt;build&amp;gt; --updates #检查 SW 更新&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site &amp;lt;build&amp;gt; --updates --site &amp;lt;source&amp;gt; #指定更新构建源码&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site &amp;lt;build&amp;gt; --trace --out &amp;lt;report&amp;gt; #保存报告和 trace&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/pwa/disable &amp;lt;enabled&amp;gt; --next &amp;lt;disabled&amp;gt; #检查 SW 停用&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/csp &amp;lt;build&amp;gt; --page &amp;lt;path&amp;gt; #检查指定页面 CSP&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site --help #查看参数&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;检查服务已完成的构建，并应用其生成的 &lt;code&gt;_headers&lt;/code&gt;。报告列出所选路径、失败项和&#10;跳过范围；代表页面检查不覆盖每个页面或全部任务。普通 UI 检查阻止 SW，&#10;需要实际 worker 的 PWA 和预取检查单独启用。&lt;/p&gt;&#10;&lt;p&gt;检查会自动识别部署子目录和默认语言首页，无需为检查临时修改 &lt;code&gt;baseURL&lt;/code&gt; 或语言设置。单页检查的 &lt;code&gt;--page&lt;/code&gt; 使用实际访问路径，例如 &lt;code&gt;/blog/zh/p/example-product/&lt;/code&gt;。SW 停用检查也使用实际部署范围；未指定 &lt;code&gt;--page&lt;/code&gt; 时自动选择语言首页。&lt;/p&gt;</description></item><item><title>约定 · UI 命名与职责</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/ui-naming/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/ui-naming/</guid><description>&lt;p&gt;概念名称见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/glossary/"&gt;项目术语表&lt;/a&gt;。本文用于定位 UI 源码；配置示例见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/articles/docs-guide/"&gt;使用指南&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="公共页面列"&gt;公共页面列&lt;/h2&gt;&#10;&lt;p&gt;文档承载横向画幅，各页面列独立纵向滚动。根导航列、面包屑列、主内容列和文档辅助列使用同一布局体系；DOM 顺序与阅读顺序保持一致。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;module/assets/css/page-shell.css&lt;/code&gt; 负责列尺寸、滚动和打印布局，&lt;code&gt;breadcrumb-navigation.css&lt;/code&gt; 与 &lt;code&gt;document-aside.css&lt;/code&gt; 负责各自列内呈现。正文表格和代码的局部滚动不作为页面列。&lt;/p&gt;&#10;&lt;p&gt;修改面包屑列时，保留已有滚动容器，避免重置画幅。实现入口为 &lt;code&gt;module/assets/js/browse/breadcrumb-render.js&lt;/code&gt;；首帧位置与历史边界见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/breadcrumb-models/#%e5%b8%83%e5%b1%80%e4%b8%8e%e7%bb%b4%e6%8a%a4%e8%be%b9%e7%95%8c"&gt;面包屑导航模型&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="样式类与行为标记"&gt;样式类与行为标记&lt;/h2&gt;&#10;&lt;p&gt;样式类表达呈现，&lt;code&gt;data-*&lt;/code&gt; 表达脚本行为，ARIA 表达可访问语义。修改其中一类时，核对另外两类及共享片段读取端。&lt;/p&gt;&#10;&lt;p&gt;公共列表与完整条目由 &lt;code&gt;module/layouts/_partials/system-ui/list/&lt;/code&gt; 提供。功能模块决定成员、字段和链接，公共组件只负责装配。根导航、主列表、选择列表与共享导航片段复用条目组件。&lt;/p&gt;&#10;&lt;p&gt;链接与按钮保持原生控件，保留键盘操作、焦点和可访问名称。选择列表与可排序列表使用各自功能入口，不把业务判断放入公共控件。&lt;/p&gt;&#10;&lt;h2 id="css-源码与发布名"&gt;CSS 源码与发布名&lt;/h2&gt;&#10;&lt;p&gt;CSS 按视觉职责命名，不复制模板目录层级。源码职责与发布资源可以不同；依赖和合并顺序直接读取构建入口，避免另维护一份文件清单。&lt;/p&gt;&#10;&lt;p&gt;以下路径相对 &lt;code&gt;module/&lt;/code&gt;。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;修改内容&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;入口&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;公共样式与配色装配&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/css/page.css&lt;/code&gt;、&lt;code&gt;layouts/_partials/system-ui/page-styles.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;页面画幅与列尺寸&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/css/page-shell.css&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;列表字段、控件与图标&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/css/list-layout.css&lt;/code&gt;、&lt;code&gt;item.css&lt;/code&gt;、&lt;code&gt;icons.css&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;正文样式&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/css/prose.css&lt;/code&gt;、&lt;code&gt;layouts/_partials/feature-document/styles.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;元信息与章节目录&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-document/&lt;/code&gt;、&lt;code&gt;assets/css/document-aside.css&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;共享面包屑 HTML&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-browse/navigation/source/fragment.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;共享片段校验与显示&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/browse/breadcrumb-source.js&lt;/code&gt;、&lt;code&gt;breadcrumb-render.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;语言与外观选项&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-preferences/&lt;/code&gt;、&lt;code&gt;assets/js/preferences/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;站点状态控件&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_shortcodes/site-status.html&lt;/code&gt;、&lt;code&gt;assets/js/site-status/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;首页艺术包装配&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/page-home.html&lt;/code&gt;、&lt;code&gt;layouts/_partials/entry-page-home/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;配色与艺术包由站点维护，修改方法见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/appearance-customization/"&gt;配色与首页定制&lt;/a&gt;。浏览来源与排序只在&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/navigation-state/"&gt;导航状态协议&lt;/a&gt;中定义；不要用 UI 命名或样式类替代该协议。&lt;/p&gt;</description></item><item><title>约定 · 导航状态协议</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/navigation-state/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/navigation-state/</guid><description>&lt;p&gt;内容归属由内容树决定，本次浏览状态由网址保存。发布网址不能用来推断内容归属。构建模型见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/breadcrumb-models/"&gt;面包屑导航模型&lt;/a&gt;，页面配置见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/layout-slots/"&gt;页面区域与布局&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="url-状态"&gt;URL 状态&lt;/h2&gt;&#10;&lt;p&gt;&lt;code&gt;from&lt;/code&gt;、&lt;code&gt;sorts&lt;/code&gt; 和 &lt;code&gt;anchor&lt;/code&gt; 放在 URL 片段中，不进入 HTTP 或 SW 缓存地址。真实查询参数仍保留在 &lt;code&gt;?&lt;/code&gt; 后。&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;/p/example-product/#from=products/examples&amp;amp;sorts=_,name-desc&amp;amp;anchor=installation&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;h3 id="from"&gt;&lt;code&gt;from&lt;/code&gt;&lt;/h3&gt;&#10;&lt;p&gt;表示文章浏览来源，指向栏目内容路径，不指向文章。有效来源必须由页面索引提供，且对应栏目包含当前文章；无效来源回到文章默认归属。&lt;/p&gt;&#10;&lt;p&gt;来源只改变根入口选中项和面包屑列，不改变正文、规范地址或完整根入口列表。栏目与汇总列表使用自身路径，不保留冗余的 &lt;code&gt;from&lt;/code&gt;。&lt;/p&gt;&#10;&lt;h3 id="sorts"&gt;&lt;code&gt;sorts&lt;/code&gt;&lt;/h3&gt;&#10;&lt;p&gt;按当前有效内容路径从根级记录各栏目排序，包含主列表。根导航列、语言前缀和文章本身不占排序位置。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;_&lt;/code&gt; 表示对应栏目的默认排序；缺少的尾项也使用各自默认值。生成链接时省略尾部默认项，保留中间占位。每列只更新自己的排序，不增加历史记录。普通点击和新标签打开须得到相同状态。&lt;/p&gt;&#10;&lt;p&gt;排序状态按栏目保存。栏目链接保留祖先状态，不将当前排序复制到子栏目；未指定状态的栏目读取自己的默认排序。&lt;/p&gt;&#10;&lt;h3 id="章节与历史"&gt;章节与历史&lt;/h3&gt;&#10;&lt;p&gt;只有章节时使用原生 &lt;code&gt;#installation&lt;/code&gt;；与导航状态并存时使用 &lt;code&gt;anchor=installation&lt;/code&gt;。排序不触发章节重新定位，正文滚动不改写网址。历史恢复交给浏览器，不在导航协议中保存滚动位置。&lt;/p&gt;&#10;&lt;h3 id="系统页面与返回"&gt;系统页面与返回&lt;/h3&gt;&#10;&lt;p&gt;语言、外观等页面使用普通链接，返回使用浏览器历史，不另存原阅读网址。无上一条历史时返回当前语言首页。&lt;/p&gt;&#10;&lt;p&gt;语言选择替换当前设置页历史。返回内容时，优先打开所选语言的真实译文；缺少译文时保留原内容并显示说明。这次选择只作用于当前标签页的一次返回，不成为全站语言偏好。会话存储不可用时，普通链接和返回仍可用。&lt;/p&gt;&#10;&lt;h2 id="源码入口"&gt;源码入口&lt;/h2&gt;&#10;&lt;p&gt;以下路径相对 &lt;code&gt;module/assets/js/&lt;/code&gt;。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;修改内容&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;入口&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;片段字段与章节读写&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;browse/navigation-state.contract.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;内容路径与排序位置&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;browse/navigation-state.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;选择有效来源&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;browse/navigation-source.js&lt;/code&gt;、&lt;code&gt;breadcrumb-controller.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;链接生成与排序刷新&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;browse/breadcrumb-links.js&lt;/code&gt;、&lt;code&gt;breadcrumb-sort.js&lt;/code&gt;、&lt;code&gt;collection-sort.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;章节定位&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;document/anchors.js&lt;/code&gt;、&lt;code&gt;document/toc.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;设置页返回与译文选择&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;pages/back.js&lt;/code&gt;、&lt;code&gt;preferences/language-page.js&lt;/code&gt;、&lt;code&gt;preferences/language-return.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;列索引与共享片段的构建入口见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/breadcrumb-models/#%e9%9d%a2%e5%8c%85%e5%b1%91%e6%a8%a1%e5%9e%8b"&gt;面包屑模型&lt;/a&gt;。修改协议时，同时核对构建端、浏览器端及&lt;a href="https://github.com/SwawHQ/banyan/blob/main/tests/README.md"&gt;导航检查&lt;/a&gt;。&lt;/p&gt;</description></item><item><title>约定 · 面包屑导航模型</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/breadcrumb-models/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/breadcrumb-models/</guid><description>&lt;h2 id="第一列与进入路径"&gt;第一列与进入路径&lt;/h2&gt;&#10;&lt;p&gt;根导航列来自当前语言的首页和直属页面。结构根页面用于归属判断，可见入口只保留已发布 HTML 的页面；根入口可以是栏目，也可以是普通页面。&lt;/p&gt;&#10;&lt;p&gt;内容声明见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/layout-slots/"&gt;页面区域与布局&lt;/a&gt;。构建入口为 &lt;code&gt;module/layouts/_partials/feature-browse/navigation/root/&lt;/code&gt;。&lt;/p&gt;&#10;&lt;h2 id="选中规则"&gt;选中规则&lt;/h2&gt;&#10;&lt;p&gt;默认归属来自真实内容祖先。&lt;code&gt;_map.toml&lt;/code&gt; 增加引用关系，不创建新页面，也不修改原文的 Parent 或发布网址。&lt;/p&gt;&#10;&lt;p&gt;浏览来源只改变本次导航。来源有效性、排序与历史规则统一见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/navigation-state/"&gt;导航状态协议&lt;/a&gt;，不能据此改变规范地址或结构化数据中的真实路径。&lt;/p&gt;&#10;&lt;h2 id="面包屑模型"&gt;面包屑模型&lt;/h2&gt;&#10;&lt;p&gt;构建期区分路径项与列来源：路径项表示目标页面，列来源提供该级的同级条目。Hugo Page 只用于构建，不传入浏览器。&lt;/p&gt;&#10;&lt;p&gt;根导航、主列表与正文保留在页面 HTML 中。面包屑内容生成共享 HTML 片段，页面只携带所需列索引。共享片段提供内容和默认排序，不保存用户状态。&lt;/p&gt;&#10;&lt;p&gt;以下路径相对 &lt;code&gt;module/&lt;/code&gt;。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;修改内容&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;入口&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;真实路径与结构面包屑&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-browse/navigation/breadcrumb/model.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;列模型与共享片段&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-browse/navigation/source/models.html&lt;/code&gt;、&lt;code&gt;fragment.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;片段发布与页面索引&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-browse/navigation/source/publish.html&lt;/code&gt;、&lt;code&gt;pack.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;索引读取与来源选择&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/browse/navigation-source.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;片段校验、加载与显示&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/browse/breadcrumb-source.js&lt;/code&gt;、&lt;code&gt;breadcrumb-controller.js&lt;/code&gt;、&lt;code&gt;breadcrumb-render.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;h2 id="布局与维护边界"&gt;布局与维护边界&lt;/h2&gt;&#10;&lt;p&gt;骨架须在片段加载前预留列宽。后续填充或排序复用已有容器；失败时显示说明，无效来源回到默认路径。DOM 与样式归属见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/ui-naming/"&gt;UI 命名与职责&lt;/a&gt;。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;assets/js/browse/canvas-position.js&lt;/code&gt; 与 &lt;code&gt;assets/js/inline/canvas-position.js&lt;/code&gt; 处理同标签页进入下一文档时的横向位置。已有滚动位置、章节锚点与用户输入优先，历史恢复交给浏览器。&lt;/p&gt;&#10;&lt;p&gt;修改后按&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/browser-regression/"&gt;浏览器检查&lt;/a&gt;选择来源、排序、章节、画幅和历史场景。浏览器层的下拉刷新差异仍需真机检查。&lt;/p&gt;</description></item><item><title>运行 · 交付与缓存</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/delivery/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/delivery/</guid><description>&lt;h2 id="配置来源"&gt;配置来源&lt;/h2&gt;&#10;&lt;p&gt;站点根 &lt;code&gt;assets/site/delivery.toml&lt;/code&gt; 是站点交付配置的唯一来源，须保留完整文件。&#10;新站点从 Banyan 根参考站点取得该文件；已有站点按参考文件补齐配置，&#10;保留自己的 SW、路由和平台值。Module 和传统主题目录不提供默认配置，&#10;&lt;code&gt;routes&lt;/code&gt; 按声明顺序使用，&#10;&lt;code&gt;routes = []&lt;/code&gt; 表示不声明缓存路由。运行时配置应用到所有语言。&lt;/p&gt;&#10;&lt;h2 id="部署平台"&gt;部署平台&lt;/h2&gt;&#10;&lt;p&gt;初次发布按&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/deploying/"&gt;首次部署&lt;/a&gt;设置平台、构建并上传。本页只说明交付配置的含义。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;platform.cloudflare.pages.enabled&lt;/code&gt; 控制 Cloudflare Pages 输出；&lt;code&gt;platform.edgeone.makers.enabled&lt;/code&gt; 控制 EdgeOne Makers 输出。启用后分别生成 &lt;code&gt;_headers&lt;/code&gt; 或 &lt;code&gt;edgeone.json&lt;/code&gt;，有重定向规则时还会生成对应配置。&lt;/p&gt;&#10;&lt;p&gt;构建命令、输出目录和工具版本在平台设置；Banyan 生成的 EdgeOne 配置只包含响应头和重定向。两种部署方式的准备步骤见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/deploying/"&gt;首次部署&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="路由和-http-响应头"&gt;路由和 HTTP 响应头&lt;/h2&gt;&#10;&lt;p&gt;通用规则在前，例外在后。以下只展示路由格式；修改已有的对应路由，不要用示例替换整个文件。保留本站需要的安全头和其他路由：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-toml" data-lang="toml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;[[&lt;/span&gt;&lt;span class="nx"&gt;routes&lt;/span&gt;&lt;span class="p"&gt;]]&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;path&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;/*&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Cache-Control&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;public, max-age=900, must-revalidate&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;sw&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;bucket&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;versioned&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;[[&lt;/span&gt;&lt;span class="nx"&gt;routes&lt;/span&gt;&lt;span class="p"&gt;]]&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;path&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;/js/*&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Cache-Control&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;public, max-age=31536000, immutable&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;cloudflare&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;pages&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;unset&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;Cache-Control&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;sw&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;bucket&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;fingerprinted&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;[[&lt;/span&gt;&lt;span class="nx"&gt;routes&lt;/span&gt;&lt;span class="p"&gt;]]&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;path&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;/sw.js&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;sw&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;bucket&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;off&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;&lt;code&gt;path&lt;/code&gt; 可为精确路径，或在任意位置包含一个 &lt;code&gt;*&lt;/code&gt;，例如 &lt;code&gt;/*.xml&lt;/code&gt;。&#10;通配符可匹配空字符串，也可跨越 &lt;code&gt;/&lt;/code&gt;。&#10;SW 匹配区分大小写的 URL pathname，保留百分号编码，不含查询参数和片段；&#10;非 ASCII 路径使用编码形式。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;http.headers&lt;/code&gt; 应用于两个平台。同一路由的&#10;&lt;code&gt;http.cloudflare.pages.headers&lt;/code&gt; 和 &lt;code&gt;http.edgeone.makers.headers&lt;/code&gt; 覆盖通用值。&#10;Cloudflare 的 &lt;code&gt;unset&lt;/code&gt; 在设置当前值前移除此前匹配的响应头。&#10;HTTP 路由保留声明顺序，由各平台按自己的规则处理。&#10;CSP 根据实际内联脚本生成，详见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/security-csp/"&gt;安全策略与 CSP&lt;/a&gt;。&lt;/p&gt;</description></item><item><title>运行 · 安全策略与 CSP</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/security-csp/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/security-csp/</guid><description>&lt;h2 id="生成与配置"&gt;生成与配置&lt;/h2&gt;&#10;&lt;p&gt;Banyan 为已启用的平台生成 CSP 响应头，并为外链脚本提供完整性信息。站点根 &lt;code&gt;hugo.toml&lt;/code&gt; 须保留：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-toml" data-lang="toml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;minify&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;disableJS&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;此设置防止 HTML 压缩再次改写脚本，使 CSP 哈希失效。&lt;/p&gt;&#10;&lt;p&gt;其他缓存、安全和权限头在 &lt;code&gt;assets/site/delivery.toml&lt;/code&gt; 中维护。修改源配置后重新构建，不直接编辑生成的 &lt;code&gt;_headers&lt;/code&gt; 或 &lt;code&gt;edgeone.json&lt;/code&gt;。平台开关和路由见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/delivery/"&gt;交付与缓存&lt;/a&gt;。&lt;/p&gt;&#10;&lt;p&gt;参考配置的 Permissions-Policy 关闭主题不需要的高权限能力。HSTS 使用 &lt;code&gt;max-age=300&lt;/code&gt;，不包含 &lt;code&gt;includeSubDomains&lt;/code&gt; 或 &lt;code&gt;preload&lt;/code&gt;；是否扩大范围由站点决定。&lt;/p&gt;&#10;&lt;h2 id="自定义脚本"&gt;自定义脚本&lt;/h2&gt;&#10;&lt;p&gt;自定义模板中的裸内联 JS 不会自动获得 CSP 授权，优先使用外链脚本。新增第三方脚本或改变资源来源后，检查实际页面和部署响应头。&lt;/p&gt;&#10;&lt;p&gt;主题的内联脚本与原生预取规则由构建统一生成哈希，无需添加 &lt;code&gt;unsafe-inline&lt;/code&gt;。预取配置见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/prefetch-stacks/"&gt;预取配置&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="验证"&gt;验证&lt;/h2&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/delivery &amp;lt;build&amp;gt; #检查交付配置与指纹发布路径&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/csp &amp;lt;build&amp;gt; #检查哈希、integrity 和响应头&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/csp &amp;lt;build&amp;gt; --page &amp;lt;path&amp;gt; #检查浏览器实际 CSP 违规&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/http/security &amp;lt;url&amp;gt; #检查已部署的响应头&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;本地检查不能代替部署后检查。尤其在 EdgeOne 上，应检查真实 HTTP 响应中的重叠规则结果。检查范围和准备步骤见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/browser-regression/"&gt;浏览器检查&lt;/a&gt;及 Skill 的&lt;a href="https://github.com/SwawHQ/banyan/blob/main/.agents/skills/swaw-banyan/references/delivery.md"&gt;交付检查&lt;/a&gt;。&lt;/p&gt;</description></item><item><title>运行 · 预取配置</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/prefetch-stacks/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/prefetch-stacks/</guid><description>&lt;p&gt;预取设置由站点完整的 &lt;code&gt;assets/site/delivery.toml&lt;/code&gt; 提供，应用到所有语言。&#10;首次部署可以保持关闭。需要启用时，在已有 &lt;code&gt;[prefetch]&lt;/code&gt; 表中把 &lt;code&gt;enabled&lt;/code&gt; 改为 &lt;code&gt;true&lt;/code&gt;，再按下方说明调整规则；不要追加重复的表。&#10;Module 不提供默认配置；未单独配置的图标和范围按本站表中的规则取值。预取按条目主图标名称和列范围匹配。&lt;/p&gt;&#10;&lt;h2 id="图标与列范围"&gt;图标与列范围&lt;/h2&gt;&#10;&lt;p&gt;&lt;code&gt;folder&lt;/code&gt; 表示集合入口策略，&lt;code&gt;file&lt;/code&gt; 表示内容页面策略。&#10;这些名称是预取提示；更换条目图标也会改变策略。&#10;只匹配条目的主 SVG 图标，正文装饰图标不参与图标分类。&#10;未配置图标、文字、图片和其他页面链接使用 &lt;code&gt;default&lt;/code&gt;。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;范围&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;含义&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;root&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;根导航，第 0 列&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;tail&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;最后的条目列；集合页为主集合列表，文章页为最右面包屑列表&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;&amp;quot;root+N&amp;quot;&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;从根导航向右 N 个条目列&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;&amp;quot;tail-N&amp;quot;&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;从尾列向左 N 个条目列&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;all&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;此图标未被其他范围覆盖的条目链接&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;只计算导航和集合条目列。文章正文、章节和元信息不参与编号。&#10;横向滚动不改变编号。没有面包屑列的文章页，根导航同时是尾列。&#10;偏移到根导航时可匹配它，超出实际列数时不匹配。&#10;偏移键统一加引号；&lt;code&gt;+&lt;/code&gt; 不能用于 TOML 裸键。&lt;/p&gt;&#10;&lt;p&gt;重叠优先级固定为：&lt;code&gt;root &amp;gt; tail &amp;gt; tail-N &amp;gt; root+N &amp;gt; all &amp;gt; default&lt;/code&gt;。&#10;例如三列页面的 &lt;code&gt;root+1&lt;/code&gt; 和 &lt;code&gt;tail-1&lt;/code&gt; 指向同一列，使用 &lt;code&gt;tail-1&lt;/code&gt;。&#10;两端的明确配置优先；显式 &lt;code&gt;off&lt;/code&gt; 阻止回落，配置声明顺序不影响结果。&#10;基础预取为 &lt;code&gt;off&lt;/code&gt; 的链接不参与预渲染。&lt;/p&gt;&#10;&lt;h2 id="配置"&gt;配置&lt;/h2&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-toml" data-lang="toml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;prefetch&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;enabled&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;default&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;conservative&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;prefetch&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;icons&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;folder&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;all&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;conservative&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;root&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;moderate&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;tail&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;eager&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="s2"&gt;&amp;#34;tail-1&amp;#34;&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;moderate&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c"&gt;# 需要按左侧深度配置时，可追加：&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c"&gt;# &amp;#34;root+1&amp;#34; = &amp;#34;moderate&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c"&gt;# 原生增强；Banyan 根参考配置对尾列文件夹使用 moderate，可改为 off。&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;prefetch&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;prerender&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;default&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;off&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;prefetch&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;prerender&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;icons&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;folder&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;tail&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;moderate&amp;#34;&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Banyan 根参考配置关闭预取。开启后，前端自动选择一个机制：&#10;原生 Speculation Rules → 已活动且匹配本站脚本和范围的 Banyan SW → link prefetch。&#10;没有可用机制时停止。浏览器支持原生规则但因设置或资源限制拒绝预取时，&#10;不额外用另一套机制强制请求。&lt;/p&gt;</description></item><item><title>示例文章</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/example-product/</link><pubDate>Fri, 02 Jan 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/example-product/</guid><description>&lt;p&gt;本文实际归属文章栏目。产品目录通过 &lt;code&gt;_map.toml&lt;/code&gt; 引用本文。&lt;/p&gt;&#10;&lt;p&gt;文章列表显示文章元信息。产品列表显示更新时间，并使用 &lt;code&gt;offer&lt;/code&gt; 显示价格。两种列表都链接到本页。&lt;/p&gt;</description></item></channel></rss>