外壳与导航契约
本契约描述 OINK v1.5.1。
权威来源与导航
| 关注点 | 权威来源 |
|---|---|
| 全局导航 | Hugo menus.main |
| Docs / Book 侧栏与翻页 | 内容树或 data/docs_nav.json |
| 根栏目切换器 | 解析后的顶层内容根 |
| 内容发现 | 各语言的本地搜索索引 |
| 页面与命令面板操作 | 共享操作注册表 |
任何功能都不能引入另一套菜单或页面树。菜单只允许一层子项交互;更深层级会警告,
并平铺到带链接的分组标题下。外部链接使用
target="_blank" rel="noopener noreferrer";内部链接保持语言与子路径感知。
顶部导航栏的桌面视图与抽屉视图投影同一棵树,每个下拉面板都是一列宽度适中的
“图标 + 标题"行——mega 面板与其 columns 菜单参数已退役,配置 columns
会发出警告并保持单列。菜单描述只是配置数据,不再渲染。链接树在空间足够时保持居中;
手机宽度先为品牌与工具按钮保留实际宽度,避免较长菜单与搜索按钮重叠。
lg 以上是文字链接,之下收缩为图标链接。lg 与 md 之间,右端保留搜索、版本、
语言、主题与 GitHub,没有菜单按钮;md 以下外观入口保留在搜索与抽屉入口旁,版本、语言与 GitHub 移入底栏工具组,此时首页
与显式 Landing 页在搜索旁增加一枚抽屉入口,展开完整的带标签菜单树。带侧栏的外壳页面
在这个位置打开自己的侧栏抽屉。显式 Landing 布局只使用 Landing 抽屉,即使内容类型
为 Book 或 Docs;同一页不会同时输出两个抽屉按钮。导航栏负责加载抽屉脚本,即使
站点自定义首页或 Landing 正文、没有调用主题的区块渲染器,菜单仍可操作。
从 md 起均不显示抽屉按钮。
主题自带的 404 页面没有阅读侧栏;即使根级 cascade 将其类型设为 Docs 或 Book,
也不会显示侧栏抽屉入口。把自定义类型加入 shell_types 只声明其外壳能力,
不会在自定义模板中创建侧栏。没有侧栏的全宽定制页应设置 sidebar_enabled: false。
语言链接指向页面译文,缺少译文时
指向对应语言首页;多个语言共享主机与 base path 时保持相对链接,只有语言拥有
独立 baseURL 时才变成绝对链接;hreflang 始终使用绝对链接,而且只列出真实译文,
不把切换器提供的语言首页回退当成译文。博客分页使用每一页自己的 canonical URL;
后续分页不输出跨语言 alternate,因为不同语言归档的分页边界未必相同。
navbar_autohide 从 768px 起只对精细指针生效,绝不作用于触控或抽屉宽度;
隐藏的导航栏不交还占位:两种状态下布局都保留导航栏横带,固定顶栏正好占满这条
横带、下边框画在带内,显现时原地淡入、不遮挡静止内容,hero 页面忽略该策略、
保留自己的叠加导航栏。首页与 hero 页面共用同一套柔和边界:导航栏不画下边框、
滚动时不投阴影,改由栏下一小段渐隐过渡收束边缘。
侧栏与翻页共享同一个根和顺序。manual_link、build.render: link、分隔行、
隐藏节点与占位节点保留各自已定义的语义。sidebar_icon_policy 可取默认的 all、
groups 或 none;图标是一对 Font Awesome class。无效策略遵循共享的警告与
回退契约。达到 sidebar_cache_limit 后,两种 walker 只有在语言、导航根与实际
影响输出的有效设置均相同时才复用中性标记。没有 JavaScript 时这份标记仍然可见;
普通外壳运行时只补上 active 路径。会输出 sidebar_headings 的 Book 页面保持页面
专属,并绕过共享树缓存。
根候选先收集可链接、非分隔项的顶层分区,再收集 sidebar_root_for: self 分区,并按 URL 去重。
两种来源都遵守显式的 sidebar_root_menu: false;未设置或 true 时保留。
当前解析出的根即使被排除在全站候选之外,仍会追加。零入口不输出控件,单入口
输出静态链接;所有 URL 保留语言和部署路径前缀。分隔项和使用 build.render: never
的分区不会成为切换器链接。
sidebar_divider 叶子保持静态标题;分区节点在两套侧栏遍历器中保留子项,标题不跳转,
启用折叠时提供真正的展开按钮。分组自身不进入翻页序列,子页保持原有顺序。配合
build.render: never 可省略分区自己的输出而不隐藏后代。面包屑显示不带链接的标题,
搜索跳过分组,导航 JSON 提升其子节点,Print 保留子文档。Book 目录保留分组标题和子项链接,
但跳过未发布的分组正文标题。toc_hide 仍隐藏整棵子树,
不能代替分组。显式导航键使用不含语言和部署前缀的路径,实际链接则保留这两个前缀。
只有以分区为根的 Docs/Book 导航才求值显式树。以首页为根的导航和其他外壳忽略
该数据及其警告。sections 数组为空时,仅在显式树适用的范围内警告并回退到内容树。
未缓存的显式侧栏根据解析后的页面身份标记当前页,并展开清单中定义的导航祖先;
节点省略 url 或页面使用自定义 URL 时仍然有效。当前页未列入清单时,树中的物理
祖先仍会展开。旧 URL 与激活路径提示仍受支持。
侧栏、翻页与导航 JSON 根据 page 解析出的页面身份选择显式分区。节点属于当前根,
条件是它就是该根、位于该根的内容后代中,或是解析到同一个侧栏根的 Docs/Book 页面。
因此手册文件可以保留在内容根目录,由 Docs 分区负责导航。选中节点的 children
定义导航层级,无须对应物理内容层级。自定义 url 不改变归属。Docs 的树不接管
独立的 Book 根,反之亦然;嵌套侧栏根只选择自己的分支。显式树未包含的根继续使用内容树。
两种权威来源都剪掉 toc_hide 子树;导航 JSON 将 manual_link_relref 保留为指向
解析目标的内部链接,不把占位页自身当成页面身份。
Book 标题与响应式目录
params.ui.sidebar_headings 默认为 false。Book 左侧显示页面树,右侧显示当前页
目录。设置 sidebar_headings: true(仅 h2)或 2、3、4(最深标题层级),才会
在当前 Book 导航项下加入页内标题。页面 front matter 可覆盖分区 cascade 或站点
设置;显式 false 可关闭继承的启用值。这个开关不影响右侧目录,也不影响它在
xl 以下移入侧栏。
文档站的 Book 不再默认启用左侧页内标题。启用时,标题分支继承父导航项的深度, 为图标与章节编号预留位置,再增加一级缩进;更深的标题继续缩进。 从右向左的布局使用相同的逻辑间距。
从 1200px 起,固定右栏按视口宽度的 20% 伸展,限制在 286–420px;flow 右栏按
22% 伸展,限制在 340–440px,仍接受 --td-shell-toc-flow-w 覆盖。
栏位占宽与可见面板共用同一宽度,直接跟随视口,不对宽度做过渡动画;
连续缩小窗口时,正文不能在拖动间隙反向变宽。长标题在栏内换行,变宽后可自然收为一行。
低于 1200px 时,目录分组移入已启用的左侧栏;低于 768px 时,位于手机抽屉内。
设置 sidebar_enabled: false 的页面在 1200px 以下隐藏目录栏。浏览器缩放遵循
这些 CSS 视口断点。桌面上折叠右栏会立即释放其全部占宽,面板保留滑动与淡出动画。
侧栏运行时
设置 sidebar_menu_foldable: true 时,各分支控制其子项的显示。
sidebar_menu_compact 不得永久隐藏已展开分支中的叶子条目。
这适用于 Docs 和 Book 的缓存树及逐页渲染树;不可折叠的树保留 compact 筛选。
仍在使用 OINK 1.2.0 的站点可能在展开后隐藏深层叶子。升级采用本修复前,
站点可设置 sidebar_menu_compact: false,同时保留折叠功能。
OINK 1.1.0 提供本节的展开状态 API 与隐藏内容隔离;1.0.0 不提供该 API。
window.OinkSidebar 管理已注册的树分支及可搬迁的 TOC、反向链接和分类法分组,
不依赖它们当前的 DOM 父节点。setExpanded(id, boolean, {source}) 对有效目标返回
true,对未知 ID 或非布尔值返回 false。getState(id) 返回新的 {id, expanded} 快照
或 null。ID 使用现有 aria-controls 指定的受控区域 ID,不能修改注册范围之外的元素。
来源为 user、active-path、responsive 和默认的 api。所有写入先提交
aria-expanded、td-is-open、本地化标签和区域的 inert 状态,再向 document 发送一次
oink:sidebar-disclosure 事件,详情为 {id, expanded, source}。重复写入相同状态不发
事件。API 恢复时保留当前路径祖先展开,用户仍可主动折叠这些分支。关闭含焦点的区域时,
先把焦点归还给展开按钮,再执行隔离。
ready 是初始活动路径补全和响应式搬迁完成后解析为 API 的 Promise;isReady 和
oink:sidebar-ready 也提供可供晚加载消费者检查的完成状态。可选的持久化由站点负责:
等待 ready,在 try/catch 中读取存储,再通过 setter 恢复有效 ID。OINK 自身保存整栏
折叠、宽度和滚动位置,不定义读者分支选择的版本/语言存储格式。
桌面折叠和移动抽屉关闭时,面板内容设为 inert,面板标记 aria-hidden。先移出焦点再
隔离,打开时先解除隔离再聚焦。面板本身继续充当 16px 指针感应区,外部恢复按钮保持
可用。悬浮、Escape、遮罩关闭、断点清理和滚动解锁保留原有行为。这些运行时属性不进入
无 JavaScript 的服务端回退标记。
TOC 整栏折叠时也隔离其隐藏面板。如果焦点原本位于折叠按钮,先移至可见的浮动恢复按钮; 恢复整栏后,焦点回到栏内可见的控制按钮。右侧内容搬入移动侧栏时,先清除原先的整栏 隔离,再由抽屉管理交互。抽屉的 Tab 循环只包括可见、非 inert 的控件,排除隐藏或 折叠区域中的后代。
沉浸式博客展示
OINK 没有 article 类型或第二套外壳。沉浸式阅读由普通博客外壳上的四个独立键 组成,可设在页面或分区 cascade 上;分区索引会重复它自己也需要的值:
博客外壳默认不渲染面包屑导航——文章应作为独立作品阅读——所以这份配置不需要
相应的键。breadcrumb 仍是普通键,页面或 cascade 可以在任何外壳上明确打开
或关闭它。
hero 在单页与分区索引上把共享特色图片用作装饰性的全出血背景。没有图片时
渲染普通开场;banner 与 wash 仍只用于单页。顶部导航栏以对比遮罩叠在 hero
上,并随页面一起滚动。
toc_style 可取 fixed 或 flow;flow 在文章旁放置更宽的导轨,并且只在滚动
之后固定。它的静止位置与文章信息行对齐;页面没有信息行时,与描述对齐。标题
换行数无法预知,因此由 docs-shell.js 测量偏移;没有 JavaScript 时,导轨从
文章起点开始。toc_taxonomies: false 移除术语云;导轨既无 TOC 又无术语云时
完全不渲染。notoc 仍是页面级 TOC 退出键。这些开关不改变署名、标签、系列、
翻页顺序、feed 或页尾组合;导轨在 xl 断点以下消失。
在页面向下滚动且页脚进入视口时,固定 TOC 导轨(fixed)会共享侧边栏的页脚可见
偏移量(--td-shell-footer-offset),使其底部可滚动区域止于页脚上方,确保
导轨底部的分类标签或末尾标题始终可通过滚轮与键盘访问;页脚尺寸或正文高度变化时(包括标签页、
博客视图切换和媒体加载),无需滚动即可更新避让边界。即使在禁用侧边栏(sidebar_enabled: false)的单栏沉浸
阅读中,该避让机制依然生效。页面无页脚时偏移量为 0;而 toc_style: flow 则依托
自身的 sticky 边界停止于正文末尾。移动端抽屉与打印输出均不受影响。(OINK 1.3.1 新增。)
搜索、操作与运行时
params.offline_search 选择启用各语言的本地索引。启用后默认也在 hugo server
期间构建;大型编辑循环可以设置 offline_search_on_serve: false。HTML 搜索出现
在首页、外壳页面,以及启用 landing_search 的落地页上。其它非外壳页面与 Print
不包含对话框、Lunr 或命令面板。
搜索元数据包括 search_keywords、默认值为 1 的 search_boost,以及
search_exclude。索引携带 URL、标题、分类法、摘录、小标题、description、
正文或摘要、根、分区、类型、关键词、boost、面包屑导航与图标。夹具预算为原始
2 MiB、gzip 512 KiB。站点可以通过 hooks/search-keywords-extra.html 返回额外
字符串。关键词用于匹配与排序;CJK 查询仅命中关键词时,结果显示页面描述或
摘录,不展示关键词列表。正文命中仍使用匹配位置附近的文字作为摘要。
以下行为已随 v1.4.0 发布。
查询统一大小写与 Unicode 全半角,按空白和 CJK/拉丁边界拆分,最多保留 24 个不同词, 并保留标识符标点。连续 CJK 字串按字面子串处理,不增加词典或远程依赖。 字面字段匹配与英文 Lunr 词干匹配支持跨字段覆盖;拼写回退仅适用于至少五个字符的 ASCII 词,允许一次编辑,八个字符起允许两次。有完整覆盖时不显示部分匹配; 否则显示覆盖数量并优先按覆盖率排序。同覆盖率中完整连续短语优先,正数页面加权 作用于各词最强字段得分之和。同一个词在其最强字段中重复出现时,最多获得不到 20% 的加分, 只在同一字段层级内调整次序,不会越过更强的字段;只出现一次时按该字段原本的权重计分。 仍然同分时按标题与 URL 排序。 先应用全局结果上限,再沿用栏目分组与菜单组序。
可选的 sections 条目包含真实渲染的 id、title;content 范围还包含指向唯一
正文的 UTF-8 字节 start 偏移。直接读取渲染内容,包括 h1/h6 与短代码标题,不从
标题或配置后的目录推导 ID。索引读取时临时选择 HTML,再恢复此前的输出上下文,
避免 RSS/Print 遍历污染 HTML 内容。精简范围不包含正文偏移。没有小节字段的旧索引仍可使用。
同页只返回一条结果,附带最相关小节、编码后的片段与附近文字;仅元数据命中时可指向
页面。保留语言和子路径 URL、排除规则及各范围的内容边界。
规范化匹配后的摘要与高亮保留原始文字。标题提取区分 id 与 data-id,忽略脚本和样式内容。
带标签的原生单选组将全部栏目与页面的 FirstSection 根并排呈现,沿用索引的根栏目权威。
每个选项保留 44 px 点击区域与可见焦点环;Tab 到达选中项,方向键切换范围,
Tab/Shift+Tab 的焦点始终留在对话框内。
过滤在排序和数量限制之前执行;其他栏目命中不会阻止当前范围内的拼写回退。
默认全部栏目,选择只在当前页面加载期间保留。
范围仅影响页面,在命令与偏好选择模式隐藏。结果数量和部分覆盖在统一底栏中显示并实时播报,
桌面端的键盘提示也放在同一底栏;手机端仅隐藏键盘提示。
输入法组字暂停延迟查询、索引加载引起的刷新及 Enter 激活。不引入新配置权威或构建步骤。
主题搜索归属检查器与站点真实语料、浏览器测试验证这些增量;维护中的 summary 索引
继续遵守 2 MiB / 512 KiB 预算。
内置操作 ID 包括 compare_translations、copy_markdown、copy_link、open_chatgpt、open_claude、
view_markdown、view_history、edit_page、create_child_page、create_issue、
create_project_issue、print_section、print、switch_preset、switch_theme、
switch_language、switch_version 与 open_github。分享栏之外的 copy_link
只出现在命令面板中。站点通过
languages.<lang>.params.ui.command_palette.commands 配置的命令可以打开安全
URL,或调用内置 ID,绝不能注入 JavaScript。剪贴板的旧式回退恢复此前的焦点、选区及其方向,
但复制期间其他控件已获得焦点时不再抢回。
OINK 1.4.0 中,阅读列变窄或文字放大时,面包屑与页面操作会分行排列。 连续长词允许换行,不裁剪路径文字,所有面包屑链接保持可用。操作菜单限制在视口 以内,文字放大至 200% 时仍保留键盘焦点与关闭行为,包括 320px 窄屏。
页面操作菜单在键盘焦点离开整组控件时关闭,包括 Tab 与 Shift+Tab 导航。 焦点在组内移动时保持展开;关闭菜单不会抢回读者已经移到别处的焦点。 在关闭的菜单按钮上按下向下方向键,会展开菜单并立即聚焦第一项操作。
编辑、历史与新建子页操作要求源文件具有仓库相对路径。物理文件名和站点工作目录
先统一为 / 分隔符,再判断包含关系。path_base_for_github_subdir 匹配归一化后的
路径:站点内内容使用相对工作目录的路径,外部挂载使用绝对路径。字符串正则可以
移除匹配的内容,{from, to} 映射可以替换它;外部来源必须显式匹配规则。
映射并整理路径后,空路径、.、绝对路径、带盘符的路径以及以 .. 路径段开头的
结果都会隐藏这三项操作。文档 issue 与项目 issue 操作仍按各自的仓库配置提供。
Windows 映射应匹配 / 而不是 \;归一化不会改变文件名大小写。
命令面板有空状态、文本搜索状态与 > 命令状态;快捷链接来自导航。它没有历史、
语义搜索、个性化或远程回退。搜索查询留在浏览器内,默认不发送遥测。
OinkSurfaceCoordinator 协调命令面板、外观面板、Draw.io、Expo 查看器、抽屉、根栏目、语言与版本菜单。各界面自行
管理焦点恢复与 Escape。已关闭的外观面板收到协调器的关闭请求时,不恢复焦点。
键盘导航会忽略可编辑控件与模态框。桌面端非模态外观面板允许搜索快捷键;移动端模态外观面板及其他已打开的 dialog(包括固定定位的 ARIA
对话框)仍独占按键。移动端抽屉内,Escape 先关闭根栏目切换器并归还触发器焦点,
再次按 Escape 才关闭抽屉;焦点移出切换器时收起弹层。/、\、f、c
打开搜索或命令;j/k 移动标题;q/e 翻页;h 改变展示方式;l/y、
t、r 分别打开语言、主题与根栏目选项。侧栏 WASD/方向键导航使用真实焦点,
不会改写 Tab 顺序。
不带链接的分隔分组按钮也参与树导航。从子页按 Left/a 先聚焦父分组,再按一次才折叠;
Right/d 展开已折叠的分组,已展开时进入第一个可见子项。上一页/下一页仍只遍历链接,
不会把分组按钮当成页面。
页面大纲从同一套标题模型与滚动容器计算后的 scroll-padding-top 推导光标和可见
标题范围;SVG 线条与圆点共享同一组动画值,不会漂移。合法 URL 片段会被解码;
非法百分号序列则回退到字面的标题 ID,建立链接索引和选中页尾请求的标题时遵循
同一规则。禁止增加臆测性的 DOM
修复遍历。这项跟踪始终由普通外壳运行时负责。params.ui.scroll_spy 与页面键
scroll_spy 在整个 1.x 期间都是静默兼容 no-op,不加载独立运行时;只有未来的
破坏性版本才会删除它们。
搜索尾部扩展
OINK 1.1.0 包含该 API,1.0.0 中不存在。
受信任的站点 JavaScript 可调用
OinkCommandPalette.registerSearchTail({id, rows, activate});YAML 和操作清单仍然只接受
数据。资源包继续按本地搜索开关装配。注册要求唯一且符合 [A-Za-z0-9][A-Za-z0-9_-]* 的
ID,以及两个函数;非法或重复注册抛出异常。返回的注销函数可重复调用,旧句柄不能删除
复用该 ID 的新注册。面板打开时的注册变化会合并调度一次渲染,注销会取消该扩展的待完成操作。
rows(context) 同步返回描述符。context 是冻结的 {query, locale, phase, pageResultCount}
快照:query 去除首尾空白,locale 使用 HTML 的语言标签,phase 为 results、empty 或
error,数量只统计上限截取后的本地页面结果。仅在非空文本搜索完成后调用扩展,不在空查询、
命令、选择或加载状态调用。扩展行按注册顺序放在本地化的 Actions 组中,排在全部原生页面及
操作之后。原生空结果、错误提示与输入触发的索引重试保留。
描述符必须提供扩展内唯一、符合相同语法的 id,以及非空字符串 title。
可选的 description、icon、disabledReason 为字符串,available 为布尔值,默认 true。
OINK 复制并冻结这些字段,把显示字符串当作文本渲染。描述符非法、ID 重复、返回异步结果或
回调抛出异常时,本轮跳过整个扩展,其他扩展不受影响。不承诺回调的精确调用次数。
activate(row, context) 只通过普通结果行的激活路径调用,收到复制后的描述符和生成该行时
的上下文,另带 AbortSignal 与 handoff()。操作待完成时阻止其他结果行激活,包括进入原生
选择菜单。同步异常和 Promise
拒绝会释放待完成状态、保持面板打开,并播报本地化的操作失败信息。成功值被忽略;成功时关闭
面板,不从其他界面抢回焦点。关闭、重新打开、渲染的查询改变或注销会取消待完成操作,旧操作
的迟到结果不能修改新会话。
打开另一个受协调器管理的界面前,调用 context.handoff()。它关闭面板,但不归还焦点,也不
取消本次激活。随后由站点管理新界面的焦点与错误提示。之后的新 Palette 会话或注销仍可取消
尚未完成的操作;成功完成不会取消已经移交的操作。OINK 不强制超时。
rows() 必须保持纯净。这是受信任代码的契约,不是安全沙箱。默认查询仍留在本地,不内置
远程服务商或遥测。扩展的网络行为和服务商所需授权由站点负责。
桌面端非模态外观面板允许搜索快捷键;移动端模态外观面板与其他已打开的对话框 仍独占按键。在移动端抽屉内,Escape 先关闭焦点所在的根栏目切换器并将焦点还给 触发器;再次按 Escape 才关闭抽屉,焦点离开切换器时也会收起弹层。 从落地页抽屉打开搜索后,关闭搜索会将焦点还给可见的菜单按钮。 在命令面板中选择视觉预设后,面板保持打开,供读者继续操作。
分享
params.ui.share 默认为空,可接受 16 个目标的任意有序子集:x、bluesky、
mastodon、facebook、linkedin、reddit、hackernews、telegram、
whatsapp、line、pinterest、weibo、chatgpt、claude、email、copy。
页面列表会替换继承列表;share: false 退出。未知项会警告并丢弃。只有普通页面
渲染分享栏;Print、Markdown 与 RSS 省略它。
目标是携带页面永久链接与标题的普通 intent 链接,外加本地 copy_link 按钮。
Pinterest 图片来自共享特色图片解析器。ChatGPT 与 Claude 接收构建期生成的永久
链接提示,与页面菜单里的助理操作相互独立。Discord 没有公共 intent 目标,因此
有意不提供。
分享栏不加载平台 SDK、iframe、脚本、样式表、计数器或 campaign 参数;只有读者
主动点击链接时才产生请求。它是一行带无障碍标签的字形。
share/items.html 解析目标,share/bar.html 负责渲染。
注记
页面注记在 annotation-items.html 中解析描述项,再通过
page-meta-lastmod.html 渲染。注记中的行内链接始终带下划线,包括弱化显示的修改时间
与上游归属信息,使读者无需仅凭颜色辨认链接。两者都可以做窄范围覆盖。各行顺序如下:
| 行 | 条件 |
|---|---|
| 最后修改 | 已设置 Lastmod |
| 上游 | front matter 中的 upstream_link 非空 |
| 翻译 | 配置的权威语言存在译文,而且本页包含作者正文 |
upstream_link 是页面级事实;cascade 有效,upstream_link: "" 表示退出。
其它上游事实按站点参数 → data/upstreams[upstream_source] → front matter 解析:
upstream_name、upstream_copyright、upstream_license、upstream_notice,
以及可选的 upstream_ref、upstream_modified。存在链接时,前四项必填。无效或
残缺的署名会警告,而且不渲染法律声明;不支持的 URL 会被拒绝。
upstream_modified 改变署名动词并链接提交历史,不增加新行。notice 页面承载
完整的许可证与免责声明。翻译说明通过 params.ui.translation_notice 选择启用,
以页面键 translation_notice 参与 cascade,跳过生成页面或无正文页面;以本语言
原创的页面可以用 translation_notice: false 关闭。
作者与系列
博客文章页头依次为标题、信息行、术语徽章、作者署名、系列条;description 在其后
引出正文。信息行 article-info.html 始终包含日期;启用 reading_time 后再增加
字数与分钟数。Front matter 的 upstream_link 与注记使用同一个页面级事实,
并在共享 URL 策略保护下增加本地化的原文链接。术语行只是裸徽章组,分类法名称
位于分组标签中,不显示前缀。术语徽章静止时是浅中性底与弱化文字,前置该分类法的
term 图标;可点击徽章在 hover 或 focus 时才取得当前分区的强调色淡铺、边框与文字。
图标词汇表由 taxonomy-icon.html 独家拥有——每个
分类法配一对图标:整体分类法一枚、单个术语一枚(folder-open/folder、
tags/tag、cubes/cube、users/user-pen、series 用
book-bookmark/book,其余用 shapes);params.ui.taxonomy_icons 可覆盖:
字符串同时作用于两个表面,taxonomy/term map 分别设置;无效输入警告并保留
内置。右栏词云只在云头戴整体图标:云 chip 保持"文本 + 计数”——分类法已经亮明
身份,再在每个 chip 上重复图标只是噪声。独立的分类法目录卡片会带一枚术语图标;
作者署名只放人物——头像、姓名与个人资料的一行简介——
不带标签或日期。列表行、卡片与术语归档共享同一形态的元数据行:日期、一条本地化
的作者与分区短语,以及由同一个 reading_time 开关控制的字数和分钟数。句子下方
是独立成行、自动换行的徽章行,按分类法字母序列出页面在全部分类法下的词条,每枚
徽章佩戴各自的 term 图标;卡片排除 authors——其句中已具名。
只有声明 taxonomies: {author: authors} 才启用作者。作者 term 页面拥有显示名称、
摘要、正文与特色图片头像;没有 profile 时,回退到链接标题、首字母与归档。
authors-resolve.html 在文章页头、列表行中保留 front matter 顺序,并为每位作者
生成一个 RSS dc:creator。没有 authors 时,旧 author 保持原样;两者同时
存在时,authors 无警告胜出。自定义作者分类法复数名按普通分类法处理。
只有声明 taxonomies: {series: series} 才启用系列。Term 页面拥有引言;不新增
参数、数据文件、封面模型或运行时。页面使用 series: [name] 与可选的
series_weight。series-pages.html 先按 weight 排有权重成员,再按日期升序排
无权重成员,并用 Path 打破平局;系列条与 term 页面共享该顺序。第一个命名系列
得到一条 HTML/Print 系列条。面板是半透明加模糊,而不是一张不透明卡片:hero
文章会把题图铺在这一段背后,不透明底色等于在画面上挖个洞;普通文章上这层色调
就落回页面自身的底色,所以一种处理同时服务两种场景。summary 拥有整行与末端
箭头;系列名连同它的分类法图标,仍是 summary 的兄弟链接,覆盖在一份隐藏的等宽
占位文字上,避免 summary 内出现嵌套交互控件。展开后先划一条细线,再在同一层
表面上把成员阅读顺序放进一个保持 DOM 顺序的自适应网格。每个链接都把序号纳入
点击目标,序号贴在固定方格轨道的末端,因此无论多少篇,标题都对齐在同一条边上;
窄屏保持一栏,只有当每个标题仍有可读宽度时才增加等宽栏,因此桌面面板能用满自身
宽度,也不会把一条选中背景拖过整篇正文。悬停与读者所在位置直接借用侧栏导航
处理这两种状态的同两种底色,当前篇再加上填充序号与加粗标题,不靠颜色单独表意。打印时显示同一份展开
列表,收为单栏。单篇系列与非 HTML 输出省略它。编号、交叉引用与聚合输出仍属于 Book。
默认文章分类法徽章会排除保留的 authors 与 series,因为专属界面已经展示
它们。显式设置 params.taxonomy.page_header 可以恢复任意一项。
博客索引与页面组合
博客分区索引使用 params.ui.blog_index:默认的 list、cards 与 gallery 都按最新
优先排列,共享 blog_index_size 分页,不按年分组。
table 显示日期、标题、标签行;关闭布局切换时列出整个分区,不分页;开启时
使用与其他布局相同的分页。卡片使用共享首图、本地化日期/作者/分区元数据、
标签与三行摘要。
分类法页(/tags/、/authors/)与其术语页共用一个页头
shell/taxonomy-head.html。分类法页以整体分类法图标的着色方块、本地化名称与
术语数开头;术语页以术语标题与取自 ui_taxonomy_pages、按当前 locale 的 CLDR
复数类别选择的页面数开头,没有渲染面包屑时标题上方再加一行
kicker,写明分类法并链回列表页——面包屑开启时它在上一行已经做了这两件事:代表
生成的分类法页的那一级面包屑借用页头同一个本地化标签,而不是 Hugo 的复数名标题。
页头之下,分类法页把术语排成单行卡片网格 shell/taxonomy-cards.html:使用次数
多者在前、同数按字母序(与右栏词云同序),以 auto-fill 填满等宽列,因此术语
很少时两张卡片也不会被拉宽到整页。一张卡片就是术语图标、术语名与页面数,整张
卡片即链接;只有作者以署名同款小头像开头,走同一个头像 partial。卡片不带描述、
不带最新一页:术语没有标题与计数之外值得一说的内容,多出的那一行只会让网格发糊。
不再有筛选芯片行与「全部」芯片:分区根已经在侧栏与顶栏里。术语页保持行列表,
作者资料页保留自己的页头。
分类法页与术语页的右栏以 shell/taxonomy-switcher.html 开头:声明的每种分类法
一行——整体图标、本地化名称、术语数——链向其列表页,当前分类法置于选中底色上。
这是从一种分类法的页面去另一种的路:词云芯片跳到术语页,词云头只负责折叠;只有
一种分类法的站点不渲染切换器。这一组与词云共用 toc_taxonomies 开关。分类法页
的词云按全站统计(taxonomy-root.html 对该 kind 不返回根),并省略自己那一组,
它的术语就是旁边的卡片;术语页保持分区作用域与完整的一组。
params.ui.blog_index_toggle 为当前分页切片渲染四种形态,读者依次循环切换
list、cards、table、gallery。OINK 1.4.0 已支持这四种形态。
配置值控制首次绘制,隐藏形态不加载图片。读者存储的选择只作用于发布了全部四种
形态的索引:切换器关闭的分区只发布一种形态,并始终显示它。Front matter 或
cascade 可为每个分区覆盖站点模式。没有切换器的 table 仍是完整且不分页的归档。
博客画廊
blog_index: gallery 将每篇文章呈现为一张可点击的封面,沿用共享首图解析器、
列表与卡片的日期顺序及 blog_index_size 分页,并保留 manual_link。
文章内容类型仍是博客;点击封面进入文章,不打开图片查看器。
params.ui.blog_gallery 接受 mode(wall、cards、seamless,默认
wall)与 size(160–360 的整数 CSS 像素,默认 240)。页面或 cascade 的
blog_gallery 块整体替换站点块。缺失或无效字段使用内置默认值,无效值产生
警告。画廊工具栏独立于 Expo 相册保存模式和大小,存储键为
td-blog-gallery-mode、td-blog-gallery-size;外层视图仍使用 td-blog-index。
展墙复用 Expo 的等高拼接算法,间隙为 6px;无缝模式去掉间隙。卡片模式采用 最短列优先的瀑布流。封面保持比例,在限定宽高比的格子中完整显示,不裁切。 画廊宽度低于 500px 时,展墙与无缝模式会进一步限制格子的宽高比,避免超长 竖图将文字列挤得过窄。 可处理且超过 960px 的封面生成 960 × 960 范围内的预览,GIF 使用静帧预览。 构建过程不新增远程图片抓取。
展墙与无缝模式在悬停或键盘聚焦时显示标题和描述。没有悬停能力时,文字始终 显示在图片下方,行间距计入文字高度;卡片模式始终显示文字。没有封面的文章 保留有标题、可点击的占位;加载失败的图片在增强后使用相同回退。链接以标题 命名,封面视为装饰图片。隐藏视图使用延迟加载。视图重新显示、侧栏改变宽度、 字体或图片尺寸加载后都会重新排版,避免项目重叠。禁用 JavaScript 时,响应式 网格仍显示链接与文字,并隐藏不可用的控件。
params.logo 始终是品牌标志;params.wordmark 或站点标题是紧凑宽度下隐藏的
文字部分。Docs、Book、Blog 与 Swagger 共享一个外壳模型。页尾顺序为分享、反馈、
注记、翻页、评论。Docs/Book 翻页遵循侧栏前序遍历;Blog 按 weight 后接日期倒序;
pager: false 退出。静态输出省略翻页 UI。
每一种实际渲染的页脚形态,都会在最底层栏右侧保留纯图标工具组,顺序为版本、
语言、主题、快捷键帮助。各菜单向上展开;版本触发器不直接显示当前分支或版本名。
胖页脚的折叠箭头排在工具组之后。低于 lg 时,底层栏放弃版权/居中/工具组的
三列布局,改为三行全宽居中堆叠,工具组在最后一行。这些全局控件不再出现在
侧栏底部;footer_style: none 会移除整条底栏。
OINK 没有归档外壳、任意深度飞出菜单、第二个导航权威、查询上传,也没有针对已
移除配置的浏览器兼容 shim。反馈只通过既有 gtag 发出 docs_feedback,在本地
保存选择,而且不替代 Giscus。
显式设置 params.ui.quick_links: [] 会关闭快速链接,不恢复默认值。
无效的 sidebar_root_link_self 会告警并采用文档规定的 true 回退。
分类法总览页与 term 页使用共享的 page_width 校验器。
译文对照
params.ui.compare: true 为存在同源 HTML 译文的 Docs、Book 和博客页面,在页面动作旁
增加纯图标的「打开双列视图」入口(图标与外壳中任何控件都不相同),并在命令面板中增加本地化的「双列视图」动作
(compare_translations)。阅读器标题、同步滚动开关、关闭图标和同步说明使用同一套
语言目录。图标入口通过悬停提示和无障碍名称提供标签。启用键盘导航时,B 在两种状态间
切换:在页面上按下打开阅读器,在工具栏或任一窗格中再按一次关闭,并沿用页面快捷键的
限制(不带修饰键、不在输入法组字中、焦点不在可编辑区域)。入口和关闭按钮声明
aria-keyshortcuts,帮助面板只在当前页面确实有目标译文时,以视图名称列出这个快捷键。
默认关闭。这是唯一站点参数,无需页面配对数据、新布局或新输出格式。把它设为
false 的语言既不提供入口,也不会成为目标。语言导航使用的首页回退不会成为对照目标;构建策略不输出 HTML 的译文(build.render: link 或
never,包括经 cascade 继承的设置)也不会。博客归档第二页及之后的分页没有对应页,因此不提供
入口、命令面板动作或快捷键。
阅读面占满窗口,两栏显示原有页面。当前页面固定在阅读起始一侧,因此从右到左的宿主页 会镜像窗格顺序。目标语言沿用既有语言顺序;选择器复用顶栏语言栏的图标、圆角触发器、 浮层菜单样式以及选项的选中与悬停状态,并支持鼠标与键盘选择。只加载选中的译文,更换目标保留同步开关状态。 每栏保留自己的语言、方向、脚注和正文组件。
小于 900 CSS 像素时,一行工具栏加一行切换栏,每次显示一个保留的窗格。标题可截断, 同步滚动和关闭按钮固定在行尾。切换栏放置语言按钮;有多个目标语言时再放一个纯图标的 目标语言菜单,不再重复窗格标题。只有一个目标时,窗格标题和切换栏都只显示语言名称, 不会出现只有一个选项的菜单。矮视口会进一步压缩两行:在 320 × 256 CSS 像素(400% 缩放)下仍保留至少 160 像素正文。强制颜色模式用边框标出当前窗格。跨越宽度断点时,语言菜单随布局 搬移,同时保留键盘焦点、菜单开闭状态和当前选中的窗格。
同步滚动按共同的可见标题 ID 匹配位置,并在相邻标题之间插值。未匹配的标题会跳过。
「同步滚动」是带标签的开关(role="switch"):窗格加载期间保留读者的选择并暂时禁用,
无法同步或窗格加载失败时显示为关闭。部分标题匹配时,以匹配标题为锚点估算中间位置;
没有共同标题时,改按全文阅读进度估算位置。两种情况下,开关旁都会出现一个不带底色的
橙色感叹号,鼠标悬停、键盘聚焦或轻触时弹出说明,指出属于哪种情况;说明可见时,
Escape 先关闭说明,再按一次才关闭阅读器。是否匹配与能否用作锚点是两回事:已匹配但
滚动不到阅读线的标题不提供锚点,也不算不匹配,因此不会触发「部分匹配」提示;如果没有
任何共同标题可以作为锚点,提示会说明当前按全文阅读进度同步。若标题 ID 重复或顺序
交叉,由于对应关系存在歧义,开关会自动禁用并在说明中给出原因,两栏仍可独立滚动阅读。主动窗格连续滚动时(触控板、
惯性滚动、按住按键),跟随窗格逐帧即时跟随;单次跳转在允许动画时平滑过渡。偏好减少
动态效果或恢复阅读位置时始终即时定位。
关闭同步开关后两栏恢复独立滚动;同步滚动按章节锚点对齐,不强求段落逐行齐平。
打开阅读器时会在分栏重排后延续当前阅读位置。焦点先落在对话框标题上,以便读屏软件播报视图;
在读者用 Tab 进入窗格之前,在这里按 PageUp、PageDown、空格、方向键、Home 和 End 会滚动阅读
窗格(小于 900 像素时为当前可见的窗格),同步随之跟随。点击关闭、按 Escape、按 B 或浏览器后退都会
恢复宿主页滚动位置,并把焦点还给打开阅读器时持有焦点的元素(例如按下 B 时所在的正文
链接);该元素已不存在或不可见时,退回到入口按钮。只有展开的语言菜单或可见的同步说明会
先于阅读器处理 Escape。刷新或前进/后退恢复到阅读器自己的历史记录时,阅读器会
在原记录上重新打开而不新增记录,因此一次后退即可关闭,前进可再次打开。这种恢复会还原所选目标语言、同步滚动、可见窗格和两侧
阅读位置,阅读器在滚动停止后把它们记录在自己的历史记录上。读者最后一次明确选择的目标语言和
同步设置也会记在本浏览器中,供以后打开时使用;无法使用存储时,回到第一个目标语言并开启同步。若刷新后
阅读器脚本仍在加载,此时后退也会取消这次恢复。窗格内有对话框时,Escape 先关闭内层
对话框。页内锚点留在当前窗格内且不增加历史记录,并像原生锚点跳转一样展开包含目标的隐藏标签页;站内其他文档链接会退出对照并跳转;
外部链接在窗格外打开。正文可读之前,窗格显示本地化的「正在加载」提示。目标请求等待期间,
iframe 初始的 about:blank load 事件会被忽略;如果 15 秒超时到达时文档仍为空白,就将其
视为加载失败。页面无法加载时,显示本地化的「重试」按钮和原页面直达链接;再次选择同一语言也会重新加载。
已接受决策记录理由和边界。
bin/check-compare.py、主题滚动几何测试和文档站 test:compare 浏览器测试负责
验证。专用八语言 fixture 是合成验证,不代表下游站点已采用。
验证
bin/check-navigation-contract.py、bin/check-shell.py、JavaScript 测试、输出
golden 与消费站点浏览器套件覆盖导航、语言与子路径链接、博客变体、页尾顺序、
键盘行为、无障碍与响应式布局。
外观控件
顶栏与底栏共用点击或键盘展开的外观控件,Landing 手机抽屉另有带标签的入口。
preset_menu 允许选择时显示原生风格单选组;dark_mode.show_menu 开启时显示
浅色、深色、跟随系统单选组。选择立即生效,面板保持打开。Enter、Space 或向下
方向键展开;方向键在组内选择,Tab 在组间移动,Escape 关闭并归还焦点。触发按钮
图标表示实际明暗状态:浅色显示太阳,深色显示月亮,跟随系统变化时也同步更新。
英文分组标题为 Style 和 Light,中文为「风格」与「明暗」。风格选项以两列独立 按钮排列,使用带主题色的纸页、叠层、笔尖或终端图标与预设名称,不显示 Aa 预览 或实验标记。站点默认项在悬停提示与无障碍名称中注明,选择后清除保存的风格。 选中项使用淡色背景与边框,键盘焦点另有轮廓线。
桌面使用锚定触发器的非模态 dialog,外部点击或焦点离开时关闭。低于 768 px 或
从 Landing 抽屉进入时,通过 showModal() 在浏览器顶层打开底部表单,提供关闭
按钮和 44 px 选项目标。关闭表单保留下方抽屉。表面协调器在展开前关闭无关弹层。
t 快捷键继续通过 switch_theme 切换明暗;switch_preset 是独立的命令面板选项。
快速关闭并重新打开外观面板时,先前排队的关闭事件不得清除新面板的展开状态。
Ink 与 Terminal 实验预设需显式配置;preset_menu: true
继续提供 Paper/Slate 与站点默认值。两者复用同一套状态、键盘、命令面板与底部表单
机制。Terminal 压紧桌面导航行,保留正文与手机触控目标尺寸。
Expo 相册
新增 type: expo 复用本外壳并提供图片相册展示。
其内容模型、控件和输出由 Expo 契约 维护。
本地组件表面
OINK 1.4.0 统一搜索/命令行、侧栏圆角与外观控件的尺寸规则。选中与悬停保持可区分,键盘焦点即时可见,偏好存储、导航和预设选择不变。不增加滑动高亮运行时。
v1.5.1 审查修正
这些修正已随 v1.5.1 发布,并属于当前消费站契约。
manual_link_relref无效时警告并回退到页面永久链接。侧栏、分区索引及导航 JSON 共用解析,包括部署子路径处理。引用缺失不得中断普通构建。- 导航 JSON 的 ID 与分区索引的查找键先移除部署前缀,再移除语言前缀。 无论默认语言是否使用独立目录,显式分区顺序和跨语言标识都保持一致。 对外链接仍保留两个前缀。
- 版本菜单与命令共用 URL 解析。页面链接先移除当前部署前缀,再拼接目标版本 URL,保留语言路径,避免重复加入旧版本目录。
- 博客列表使用自己的分页:本地化导航采用带
aria-current的普通链接,head 的prev/next指向列表页。博客列表不再显示文章阅读顺序的翻页器。归档分页 及其 head 链接仅用于 HTML;Print 只生成一份完整的分区聚合文档,不按 HTML 归档页数重复生成。 - 所有仅有导航栏的页面,包括沉浸式博客文章,都提供移动端站点抽屉。 语言、版本和仓库入口在抽屉中可达。关闭的侧栏抽屉不向视口投射阴影。
- 两种树遍历器的
groups图标策略都包括导航根、顶层条目和有子项的条目, 更深层的叶子不显示图标。 - 没有目录、分类法输出或反链时,不渲染空面板和控件。仅有分类信息的右栏 保留收起/展开入口,标签描述侧栏操作。Book 目录在作者编号旁禁用浏览器 自带的列表编号。
- Escape 关闭语言、版本和工具悬停菜单并将焦点返回触发器,不会重新打开菜单。 复制、反馈、双列视图加载和 Expo 边界控件保留当前焦点。