架构契约
本契约描述 OINK v1.5.1。
Hugo 工具链
维护中的站点、开发、CI 与发布验收统一使用 OINK v1.5.1 和 Hugo Extended 0.168.0,固定这套工具链。
禁止启用 --panicOnWarning 或 HUGO_PANICONWARNING。告警保持可见并接受审阅;
上游 LibSass 弃用告警允许出现,不会让成功的构建失败。无效输入测试直接检查对应
告警和安全降级产物。
主样式与 ReDoc 样式使用 Hugo 内置 LibSass,普通用户无需安装 Dart Sass 或其他 Sass 程序。项目变量与项目样式的 SCSS 钩子保持可用。后续升级必须保持这条依赖 边界,并同步修改要求、检查器、CI 固定版本与双语契约;历史发布和研究记录保留 当时的工具版本。
OINK v1.5.1 模块要求 Go 1.27.3,开发与 CI 也固定使用此版本。 Go 用于解析 Hugo Modules;已准备好传统主题副本的站点无需 Go。
仓库与装配
仓库根目录是一个完整的 Hugo 模块与主题,不是站点,也不是 npm workspace。
Hugo Extended 使用内置 LibSass 编译 SCSS,并渲染模板。浏览器运行时与第三方资源都已提交到仓库,
因此普通构建不会访问网络。公开的双语文档、示例与浏览器测试位于同级的
oink.pgsty.com 仓库;主题仓库只在 tests/site/ 中保留范围明确的内部回归
夹具,不再维护独立的公开示例面。
生成的 public/ 与 resources/ 目录绝不是源文件。随主题内置的运行时、字体
家族与 Font Awesome 字形定义属于受支持的发行内容,并非待清理的死代码;
VENDOR.json 与 bin/check-vendor.py 固定其完整性。OINK 发布完整的受支持
Font Awesome 发行包,因为用户编写的内容可能使用主题模板本身没有引用的图标。
Font Awesome 官方编译 CSS 作为一份稳定、带指纹的 vendor 样式表发布,并排在由
主题与消费站 SCSS 编译出的指纹 main.css 之前。站点样式的普通修改不会再让图标
发行包失效,同时常规层叠顺序仍允许站点覆盖它。KaTeX、DocSearch、Swagger 与
Asciinema 等能力样式继续保持独立,只在实际使用时加载。内容指纹使不可变 URL 成为
可能;HTTP 缓存响应头属于部署宿主,而不是 Hugo 主题的职责。
Hugo 类型 docs、book、blog 与 swagger 选择阅读外壳;
params.ui.shell_types 可以增加类型。落地页使用 layout: landing。OINK 没有
article 类型或第二套博客外壳;沉浸式页面只是外壳契约
定义的一种博客展示方式。
layouts/_partials/shell/config.html 解析共享外壳事实。布局必须先通过
content/render.html 渲染,再执行 scripts.html,因为渲染钩子与 shortcode
会在 Page Store 中登记能力标志。覆盖时应选择范围最窄的 partial;若合并会改变
Hugo 的查找优先级,即使几个基础模板看起来相似,也应保持分离。
配置与诊断
主题策略位于 params.ui.*;comments.giscus、plantuml、drawio 等包含多项
设置的集成保留在顶层。布尔功能直接使用布尔值,除非它还包含多项设置。页面级
覆盖会去掉 ui. 前缀:params.ui.image_zoom 对应 image_zoom,front matter
中绝不嵌套 ui map。hugo.yaml 声明公开默认值;对应的解析器与检查器定义
任何可选配置的结构或范围。
无效输入遵循同一条规则:警告中写明输入值、允许的结构与安全回退,然后使用该
回退,或省略不安全的功能。普通构建与预览保持可用;告警和降级产物由对应检查器直接验证。主题绝不调用 errorf,check-params.py 会强制守住
这条边界。不要为无法到达的状态增加臆测式校验。
OINK 没有通用的键名重命名注册表。仍需给出迁移诊断的过渡,应在所属解析器中 添加针对性警告,并配严格的反向测试;已经移除的键绝不能作为兼容路径继续读取。
可能联网的功能必须显式启用,并以关闭方式降级。OINK 1.4.0 启用 PlantUML 且未配置端点时
使用本地渲染,显式 plantuml.svg_image_url 才选择服务端模式。Draw.io 需要
drawio.drawio_server,Algolia 需要
appId、apiKey 与 indexName;配置不完整时发出警告,而且不产生网络请求。
Draw.io 只在渲染内容含 PNG 或 SVG 候选图片时加载,并且每个不同的图片 URL
只检查一次。
图表端点必须是字符串,内容为带主机的 HTTP(S) URL 或同站路径。不支持的协议、
省略协议的 URL、反斜杠、空白字符及缺少路径的同站引用都会告警,并在选择运行时前关闭该集成。
plantuml: true 或未配置端点的 plantuml.enable: true 选择浏览器渲染。固定的两份本地
资源(@plantuml/core 1.2026.9 与 Viz.js 3.24.0)仅在包含 PlantUML 围栏的 HTML 页面
加载。普通构建和读者无需安装 Java、Graphviz 可执行程序或 npm 包,也不依赖 CDN 或
渲染服务。非空端点继续选择服务端模式,保留地址校验与 svg 行为;非法端点不回退到
本地模式。本地渲染不会下载可选库、主题、include 文件或外部资源。生成的 SVG 以 Blob
图片显示,不插入页面 DOM。输入错误或资源加载失败时保留可读源码;独立 Print、Markdown
与 RSS 保留源码,不加载运行时。
添加嵌入参数时保留编辑器 URL 原有的查询参数与片段。消息必须同时来自当前 编辑器 iframe 及其配置的源;无关或格式错误的消息会被忽略。图表数据只发送到 该源。导出结果必须是 PNG 或 SVG 的 data URL。
Mermaid 与本地 PlantUML 的小型调度器只出现在使用它们的 HTML 页面;大型引擎 在可见图表接近视口时加载。同页共享引擎,主线程串行执行,未引入 Worker、新依赖 或构建步骤。缺少 IntersectionObserver 时使用滚动与尺寸检查。普通浏览器打印不等待 异步渲染:已有图显示图片,其余保留源码。独立输出不变。
界面本地化
OINK 1.1.0 将原生界面语言包扩展到下方列出的完整语言集合;消费站点编写的正文 仍需自行翻译。
OINK 为
google/docsy@64f51c5
中现有的 31 个 locale 文件名提供原生界面文本,并额外保留通用 zh 作为简体中文
默认值:
这些语言包覆盖主题界面文案,站点正文仍由站点自行翻译。 Docsy 以后增加的 locale 不会自动成为 OINK 支持项;它必须先补齐完整的 OINK 词条,并接受与现有语言相同的审校。
i18n/en.yaml 管理消息 schema。OINK 的 32 份语言包都必须拥有完全相同
的消息集与原生界面文本;只有经过审查的产品名、标点、通行缩写或目标语言真实
同形词可以与英文保持相同,不再生成整段英文 fallback。zh 与 zh-cn 使用简体中文,
zh-tw 使用繁体中文。
当前 Hugo 基线允许通用 zh 语言与地区化中文语言包并存时使用 locale: zh,也可
选择 locale: zh-CN。两种配置都不改变语言包文件名 i18n/zh.yaml。
%s、{count}、{{ .Count }} 等运行时占位符可以移到符合目标语言语法的位置,
但字节内容必须保持不变。取值可以是字符串或 Hugo 复数消息映射。复数映射使用该
语言支持的类别(zero、one、two、few、many、other),必须包含 other,
每种形式都是包含相同占位符的字符串。语言包不得包含隐藏的双向文本控制符;
阿拉伯语、波斯语和希伯来语的方向仍由消费站点的语言设置(direction: rtl)
决定,不得把方向字符塞进译文。
bin/check-i18n.py 会检查 locale 集合、schema、取值类型、占位符、方向控制符,
以及少量已审查的英文本地同形词。因此增加可见字符串时,必须在同一变更中为每份
语言包提供译文,不能再运行 fallback 生成器。
特色图片
Hugo 的 images 是唯一的创作 API;params.images 只作为全站社交卡片回退。
| 来源 | 阅读列表缩略图 | 社交卡片 |
|---|---|---|
页面 images,或页面包中的 **featured*、*feature*、{*cover*,*thumbnail*} |
是 | 是 |
分区 cascade.images |
是 | 是 |
站点 params.images |
否 | 是 |
images: [] 会清除显式值或 cascade 继承值,但不会禁止发现页面包资源。只把解析
到的第一张图片作为代表图。Hugo 可以裁剪本地可处理的位图;SVG、static 与远程
资源仍然有效,只是不能执行 Hugo 图片操作。
featured-image-resolve.html 统一决定来源优先级与相对、绝对 URL。页面自己的
显式 images 优先于页面包资源,页面包资源优先于继承的 cascade 图片;显式值与
继承值恰好相同时也遵守此顺序。有源文件的页面通过原始 front matter 判断是否显式
声明,由 Hugo 解析 YAML、TOML 或 JSON;没有源文件的生成页面将解析后的 images
视为显式值。列表缩略图、Open Graph/Twitter/schema
帮助模板、作者头像、Pinterest 图片与博客展示都消费同一个决定。
params.ui.featured_image 只用于博客,默认值为 none;页面或 cascade 可用
front matter 覆盖。banner 在单页标题上方渲染图片,wash 用图片给页头着色,
hero 在单页与分区索引上把图片绘制为外壳背景。缺少图片或使用非 HTML 输出时
不渲染图片。
输出与运行时
每个基础模板都会设置 Page.Store.tdOutputFormat:
| 输出 | 契约 |
|---|---|
| HTML | 完整的语义内容;只为实际用到的能力加载本地运行时 |
| 展开的内容;不含外壳导航、搜索或图片缩放运行时;共享操作层仍支持明确的打印控制 | |
| Markdown / LLMS | 保持源 Markdown 形态,不含 td- 组件标记 |
| LLMSFULL | 按顶层 section 选择启用:每个启用 section、每种语言一份 llms-full.txt,按阅读顺序拼接同一份 Markdown |
| RSS | 安全的静态摘要,或明确省略 |
| NAVJSON | 按站点选择启用:每种语言一份 navigation.json,序列化侧栏与 pager 已经在读的导航权威 |
| BookManifest | 选择启用、供 EPUB/PDF 打包工具消费的有序 JSON 交接 |
各输出格式按既定顺序执行。一次渲染会在整个输出期间保持自己的可变格式状态;摘要
辅助逻辑不得把较早的格式值恢复到 RSS 渲染中。但在 Print 内,Hugo
可能并行渲染同一 Book 页面与相互重叠的聚合。因此每页由一个缓存 coordinator 按
固定顺序生成普通与整书两种变体,各调用方只选择自己需要的形态。普通 Print 保留
页面局部标题与带路由的 xref URL;Book 聚合保留带命名空间的标题与文档内 xref。
正文移入 Print 之前,相对链接按各自来源页面的 HTML URL 解析。单页和聚合输出
都保留语言与部署路径前缀、查询参数和编码路径。纯片段链接仍留在当前文档,交由
标题和脚注命名空间处理;规范路径与外部链接保持原目标。
只改写实际的 href 属性;title 等非链接属性内即使出现相同文字,也必须原样保留。
标题片段在命名空间匹配前只解码一次百分号编码,涵盖 Unicode 与编码后的 ASCII。
字面加号仍为加号,格式错误的转义保持原样;ID 与属性中的 HTML 实体单独解码。
片段规范化不会改动路径、查询参数或外部来源。
Tabs 及其他 Markdown shortcode 内渲染的标题使用相同的命名空间,
即使 Hugo 没有将它们纳入 Page.Fragments。
以实际渲染的标题 ID 为准,保留中文、字面加号和百分号序列,不从转义后的标题自链接反推 ID。
Landing 页面配置 RSS 输出后,通过共享 RSS 渲染器生成静态 feed。 声明的 alternate 输出必须存在实际文件;省略交互式 Landing 组件不等于省略 feed。
Print 页面在送往纸张之前也是可供浏览器阅读的文档。屏幕预览中的宽表格保留带名称、 可键盘聚焦的滚动区,不得撑宽整个页面;打印媒体样式在实际打印时展开这些区域。 表格无需加载运行时;RSS 表格仍是不可聚焦的静态内容。
站点自行选择是否启用自定义输出;OINK 不会强制生成昂贵的整书聚合。HTML 加载 共享操作层、核心层,以及由页面 flag 选择的稳定第一方能力分片。需要模板化的能力 每种语言至多发布一份;flag 只决定引用哪些 script tag,绝不再生成新的组合 bundle。 Print 保留操作层,并且只加载渲染打印功能所需的运行时。大型第三方 UMD 文件保持 独立;未使用的功能运行时不会出现。
顶层 section 在自己 _index front matter 的 outputs 中列出 LLMSFULL 才会启用它,
主题绝不替站点把它加进输出集合。逐页 Markdown 与全文包由同一个渲染器产出,因此全文包
就是那份语义 Markdown(同样不含 td- 组件标记)按侧栏与 pager 的阅读顺序拼接。在顶层
之下启用会告警且不产出任何文件,普通构建仍然可用,检查器直接验证告警与已禁用的输出。
站点在 outputs.home 中启用 NAVJSON,为每种语言在语言根下发布一份 navigation.json。
它序列化侧栏与 pager 所读的同一条权威链:存在显式 data/docs_nav.json 树时用它,否则用
带 weight 的内容树。数组顺序就是契约,weight 绝不序列化,该输出标记为 notAlternative。
schema/nav.v1.schema.json 为该格式提供版本,它是手写的契约产物,随模板与检查器一同修改,
不受生成式配置 Schema 漂移门禁管辖。两种输出默认关闭,都不启用的站点构建结果逐字节不变;
bin/check-agent-indexes.py 是它们的归属检查器。
只有 Book 根在 outputs 中明确列出 BookManifest 时才会生成它。它引用该 Book
既有的逐页 Markdown,并记录派生出的页面顺序、标题、编号目标与 xref;主题不会在
其中猜测出版元数据。
主题仓库提供 bin/book-epub.py 与 bin/book-pdf.py 作为显式出版步骤,并用
bin/check-book-epub.py 与 bin/check-book-pdf.py 承担产物门禁。EPUB 打包器组合
BookManifest 与同一份整书 Print HTML,消费站另行传入出版 metadata;PDF runner
只在临时回环地址提供该 Print 产物,通过 script-src 'none' 内容安全策略调用显式指定的
Chrome/Chromium 二进制,输出带 CSS 页码的 A4 页面。两种工具都会拒绝缺失资源或越出构建树的资源;网络资源
与覆盖已有输出分别需要独立的显式开关。网络 opt-in 只允许被动 HTTP(S) 媒体,远程脚本与
本地文件协议仍属非法。EPUB metadata 文件中的相对资源以该文件所在目录为基准,不依赖
调用者的工作目录。普通 Hugo 构建不会执行出版工作;PDF 仍从 Print 派生,而不是另一种
模板输出。
PDF 服务还会应用 CSP sandbox、拒绝 meta refresh 导航,并拒绝指向构建树以外的 符号链接。没有网络 opt-in 时,图片与媒体请求仅限回环同源地址和 data URL, CSS 或 SVG 发起的请求也受此限制。
性能规则如下:
- 若站点级资源或
partialCached结果可以承担工作,不要为每一页遍历.Site.Pages; .Content只渲染一次,完成后再读取 Page Store 标志;- 直接输出正确标记,不要扫描 DOM 后再修复;
- 浏览器工作按资源 URL 分组,而不是按 DOM 实例重复;
- 成本显著的普通输出应保持选择启用;
- 默认不输出 Speculation Rules:必须先由一个明确的生产消费站用可回滚的
moderate实验测量Sec-Purpose: prefetch请求、实际命中导航、传输字节与 CSP 影响; - 校验确实可达的作者输入,不校验假想的内部状态。
bin/measure-baseline.py 测量构建时间、输出体积、bundle 数量与 shortcode
密度。
单页 Print 只输出一次页面摘要。分区 Print 将所有纳入后代页面的数学能力标志 传递到聚合根,因此目录页本身没有公式时,仍会按子页需要加载本地 KaTeX 样式。 完全没有公式的打印文档不加载这些样式。
信任边界、CSS 与无障碍
作者可以启用 Goldmark unsafe,但配置与组件参数不能视作原始 HTML。共享属性
策略使用允许清单、校验 class token、放行 data-* 与 aria-*,并在丢弃
style、srcdoc、on*、保留属性与未知属性时发出警告。需要本地 URL 或明确
绝对 URL 时,URL 帮助模板会拒绝危险协议与协议相对 URL。公开 API 承诺支持的
远程 URL 仍然可用,但构建时绝不抓取它们。
普通图片、Gallery 及缩放原图的 URL 在校验后仍须按 HTML 属性转义。
引号与 & 保持为 URL 的内容,不得生成新属性或被当作 HTML 实体解码。
主题输出使用 td- class、data-td-* 属性与 --td-* 自定义属性;.steps、
.cards、.full-width、.wide、.expand 等作者标记保持无前缀。CSS 支持 RTL、打印、强制颜色、
减少动画、超长 token 与窄视口。主题拥有的装饰图标带 aria-hidden;只有包含
任务列表或原始 Font Awesome 元素的页面才加载作者内容无障碍修复。
阅读容器区分指针聚焦与键盘导航。由指针聚焦的 main 区域、表格滚动区或代码 pre
不会仅因读者随后按键而出现边框;Tab、失焦或新的非指针聚焦会清除这项豁免。普通控件
保留自己的焦点样式,滚动容器保留 tabindex,跳过导航的目标在标题附近显示局部边框,
不再包围整篇文章。强制颜色模式保留键盘提示,不使用全局焦点边框重置。
字体角色为 ui、body、heading、code、display、meta、brand 与 print,
通过 --td-*-font-family 暴露。ui 是主字体:body 经它解析,heading 又经
body 解析,因此赋一次值即同时移动界面、正文与标题。params.ui.typography
可取 technical 或 system;两者编译到同一份样式表,不加载运行时。旧
Bootstrap/Docsy Sass 变量继续为这些角色提供初值。
params.ui.fonts 让配置层触达同一组角色,供不愿挂载 SCSS 或新增样式表的站点
使用。它只写字体族名,绝不加载字体文件:所写字体族必须是读者已有的,或站点
自己用 @font-face 声明过的,这也让该键留在网络契约之外。取值只放行纯粹的
字体族语法,输出的 :root 块由匹配到的片段重新拼装;未知角色或不安全取值只
告警并单独丢弃。该块在样式表之后渲染,正是这一点让作者字体在同等优先级下压
过预设。外壳读站点的字体,不自带字体:Book 的编号与题注用正文字体,而非某种
技术字体。
强调色按角色拆开。强调文字(链接、外链、行内代码)跟随 Bootstrap 链接
族与 --bs-code-color,主题色永不重声明它们;行内代码随视觉预设变化:Slate 保留胭脂红明暗对,Paper 使用墨色文字与淡底,
使一页密集的标识符读成「代码与正文」而非「代码与链接」。强调底(选中行、
指针划过导航行时那层更灰的底、hover 淡铺、目录药丸与轨道光点、徽章 hover、
卡片 hover 时的外边、分享按钮 hover 时的实心底、文本选中、焦点环)跟随
--td-accent、--td-accent-rgb 与 --td-accent-hover,它们默认取链接族,也是
params.ui.theme_color 唯一注入的属性。属于外壳而非正文的文字同样跟随它们:
视口正停在其上的目录锚点、以及指针或键盘焦点落在其上的 Book 章节小标题,
按分区颜色点亮,而不是链接蓝。theme_color 与 theme_color_dark
取 #rgb/#rrggbb;front matter 与分区 cascade 覆盖站点值。未配置的站点不注入
任何内容。解析失败的值告警并保留默认配色。解析成功但在主题自身画布上低于 4.5:1
的颜色,带可抑制 id 告警并照常生效:该检查是建议性的,只有解析失败才丢弃颜色。
亮色是主键:没有有效 theme_color 的 theme_color_dark 告警并被忽略,一页要么
两种模式都着色,要么都不着色。省略暗色一半时,向白按 4% 步进提亮,直到在暗色画布
上达到 4.5:1。注入的每个字节
都由解析出的整数通道格式化,绝不来自作者文本。同一个解析器同时回答 head 注入块
与侧栏根切换器的「这一页是什么颜色」。
视觉预设
OINK 1.2.0 默认使用 Paper。params.ui.preset 接受 paper、slate,以及显式
选择的实验预设 ink、terminal;非法值与保留名称(folio、canvas)告警并回退到
paper。params.ui.preset_menu 默认 false;true 提供 Paper、Slate 与站点默认值,
列表指定可选项并可显式开启实验。列表必须包含站点默认值,缺失时告警并补入。不支持页面级预设。
Hugo 为所有文档根元素输出 data-td-preset 与 data-td-site-preset,包括 404
和打印输出。开启读者选择时,head 内联脚本在 CSS 加载前校验 td-preset。选择
带默认标记的预设会删除该存储键。非法存储值被清除;存储被禁用时,控件仍可在当前
页面使用,并显示无法持久化的提示。storage 事件同步标签页,td-preset-change
携带 {preset, previous, stored}。明暗状态独立使用 data-bs-theme、
td-color-theme 与 td-theme-change。浏览器栏颜色跟随实际明暗和预设。禁用
JavaScript 时显示站点默认的浅色预设;外观控件需要 JavaScript。
四套预设编入同一个样式表。Slate 保留 v1.1.0 的基础色板选择器与值。Paper 调整
配色和少量组件规则,不改变外壳列宽、断点或全局间距。Paper 深色块重声明浅色块的
每个色板 token,并覆盖嵌套深色区域。字体角色保持同等选择器优先级,顺序为预设、
typography: system、head 输出的 params.ui.fonts;站点的
_styles_project.scss 仍在最后。brand 单独控制字标。Paper 使用本地 IBM Plex Sans,
Slate 保留 Inter;两者的字标保留 Chakra Petch,代码保留 IBM Plex Mono。
系统排版模式不请求内置文字字体,除非站点显式覆盖角色。没有新增外部字体请求。
Ink 统一使用 Inter,配合红色标记、正文链接下划线、直角与无阴影。Terminal 使用
等宽界面和标题、Plex Sans 正文、青色链接、琥珀强调、2 px 圆角与无阴影;仅压紧
桌面导航,保留正文行长与手机触控目标。CSS 标题标记使用空的无障碍替代文字,
不支持的浏览器省略标记。显式 fonts.ui 仍控制主字体,除非设置了有效的
fonts.body。参见实验记录。
Paper 在浅色与深色模式下均不再绘制正文 h2 标题右侧的装饰横线。
标题的字体、间距、锚点与正常换行保持原样,仍支持站点自定义的标题边框。
Giscus 自动色板同时跟随风格与明暗;显式主题或浅深色样式表配置仍优先。打印使用 当前预设的浅色配色与白纸背景,即使屏幕为深色。Mermaid 与 ECharts 继续只跟随 明暗,API 组件保留供应商色板。参见已接受决策 与本地验收记录。
译文阅读运行时
唯一设置是布尔参数 params.ui.compare,默认 false,可按语言覆盖。无效值会警告并
保持关闭。Hugo 只从同样开启对照的语言中的真实译文页面推导候选,并输出少量描述数据。
入口脚本在点击后加载阅读器,阅读器使用两个同源 HTML frame,不生成语言组合或新的
内容输出。保留的宿主页使总数为三个活动文档。读者偏好(最后的目标语言与同步设置)存放在
localStorage 的 td-compare-reader 键中,读写均包在 try/catch 里;可恢复的会话(目标、
同步、可见窗格和语义书签)只存放在阅读器自身历史记录的 history.state.oinkCompareSession 中。
oink_compare_pane=1 仅在已打开阅读器拥有的 frame 中启用内部窗格状态。顶层访问
该 URL 仍显示普通页面。自定义脚本可以在 head hook 中读取 window.OinkComparePane。
窗格状态停用外壳运行时与快捷键、搜索初始化、评论和主题管理的统计,保留正文运行时与
样式。bin/check-compare.py 把每个浏览器运行时归类为窗格中停用、窗格中运行或仅限
宿主页,新增运行时必须声明它在窗格中的行为。开启对照后,生产构建通过主题自带的、
能识别窗格的模板渲染 Google Analytics,而不是 Hugo 内置 partial;因此站点覆盖的
google_analytics.html 不再生效。Frame 隔离文档 ID,同源内容仍属于受信站点内容。
窗格需要 frame-src 'self' 和同源嵌入。普通 canonical 链接继续标识原页面。Print
和机器输出不包含对照控件或对照运行时。
窗格以其启动脚本报告 DOMContentLoaded 为就绪,而不是等待所有图片和嵌入内容加载完成;
缓慢的资源不会推迟或销毁已经可读的窗格。无效文档在其 load 事件或 15 秒文档超时后
判定为失败。iframe 初始的 about:blank load 事件会被忽略,但超时时仍为空白的文档
会判定为失败。浏览器在就绪时测量几何位置,并在窗口尺寸、frame 的 load 事件、
字体、图片以及折叠项或组件布局变化(包括 td:tab-shown)后重新计算。用户输入决定当前活动窗格,程序驱动的跟随滚动不会夺取控制权。滚动更新
按动画帧合并。主动窗格连续滚动时,跟随窗格逐帧即时跟随,因为每帧重新开始平滑滚动会
让跟随窗格停滞;单次跳转在允许动画时平滑过渡,偏好减少动态效果或恢复阅读位置时直接
定位。关闭或替换窗格时会终止对应的事件监听器、观察器和加载超时计时器。原生
dialog 的 inert 机制将焦点限制在阅读器内,子文档键盘事件处理则保留窗格内组件弹窗
的交互。阅读器的历史记录在页面刷新或前进/后退恢复后仍然保留:入口脚本将恢复状态
绑定到该历史记录的 token,并在阅读器脚本加载完成后再次校验;若加载期间已离开该
记录,则取消恢复。在原记录上重新打开时保留既有 token 且不重复写入历史。历史记录
跳转会先处理显式关闭或用户排队触发的重开,再执行自动恢复。跨越窄屏断点迁移语言
菜单时,会先更新窗格可见性与不可交互状态,再恢复菜单的键盘焦点与展开状态。
发布状态
发布流程中应分别跟踪本地验证、模块打标、消费站版本更新与站点部署。
v1.5.1 审查修正
v1.5.1 继续使用 Hugo Extended 0.168.0 和 Go 1.27.3。 验证报告必须注明实际工具链和本地模块来源。
Feed 在应用 services.rss.limit 前按日期倒序排列,无日期条目省略 pubDate。
RSS 摘要和页面订阅源可能在 RSS 阶段共用页面 Store。摘要渲染保持该 Store 的 RSS
格式状态,不恢复陈旧的 HTML 状态,同时保留手工摘要分隔符的语义。
焦点指示器使用当前预设的不透明链接颜色。导航栏控件及会裁剪内容的代码块、 FAQ 容器保留可见的键盘焦点。强制颜色模式明确显示当前导航项和页脚字标。 标题及字段自链接保持键盘可达,打印链接保留下划线。本地 Bootstrap RTL 制品提供方向规则,但不替换主题的字体角色。正文列表间距不应用到组件列表。
配置 schema 接受 translation_notice 为 false 或非空语言代码字符串,
语言是否存在由所属解析器验证。分页和面包屑标签覆盖全部 32 种语言。
缩略图替代文本直接使用页面标题,不添加英文前缀。