外壳与导航契约

权威来源与导航

任何功能都不能引入另一套菜单或页面树。菜单只允许一层子项交互；更深层级会警告， 并平铺到带链接的分组标题下。外部链接使用 target="_blank" rel="noopener noreferrer"；内部链接保持语言与子路径感知。

顶部导航栏的桌面视图与抽屉视图投影同一棵树，每个下拉面板都是一列宽度适中的 “图标 + 标题"行——mega 面板与其 columns 菜单参数已退役，配置 columns 会发出警告并保持单列。菜单描述只是配置数据，不再渲染。链接树在任何宽度都保持居中： lg 以上是文字链接，之下收缩为图标链接。lg 与 md 之间，右端保留搜索、版本、 语言、主题与 GitHub，没有菜单按钮；md 以下这些工具移入底栏工具组，此时首页 与显式 Landing 页在搜索旁增加一枚抽屉入口，展开完整的带标签菜单树；其余宽度 与页面一律不渲染抽屉入口。语言链接指向页面译文，缺少译文时 指向对应语言首页；多个语言共享主机与 base path 时保持相对链接，只有语言拥有 独立 baseURL 时才变成绝对链接；hreflang 始终使用绝对链接。 navbar_autohide 从 768px 起只对精细指针生效，绝不作用于触控或抽屉宽度； 隐藏的导航栏不交还占位：两种状态下布局都保留导航栏横带，显现时原地淡入、 不遮挡静止内容，hero 页面忽略该策略、保留自己的叠加导航栏。

侧栏与翻页共享同一个根和顺序。manual_link、build.render: link、分隔行、 隐藏节点与占位节点保留各自已定义的语义。sidebar_icon_policy 可取默认的 all、 groups 或 none；图标是一对 Font Awesome class。无效策略遵循共享的警告与 回退契约。

沉浸式博客展示

OINK 没有 article 类型或第二套外壳。沉浸式阅读由普通博客外壳上的四个独立键 组成，可设在页面或分区 cascade 上；分区索引会重复它自己也需要的值：

featured_image: hero
toc_style: flow
toc_taxonomies: false
sidebar_enabled: false

博客外壳默认不渲染面包屑导航——文章应作为独立作品阅读——所以这份配置不需要 相应的键。breadcrumb 仍是普通键，页面或 cascade 可以在任何外壳上明确打开 或关闭它。

hero 在单页与分区索引上把共享特色图片用作装饰性的全出血背景。没有图片时 渲染普通开场；banner 与 wash 仍只用于单页。顶部导航栏以对比遮罩叠在 hero 上，并随页面一起滚动。

toc_style 可取 fixed 或 flow；flow 在文章旁放置更宽的导轨，并且只在滚动 之后固定。它的静止位置与文章信息行对齐；页面没有信息行时，与描述对齐。标题 换行数无法预知，因此由 docs-shell.js 测量偏移；没有 JavaScript 时，导轨从 文章起点开始。toc_taxonomies: false 移除术语云；导轨既无 TOC 又无术语云时 完全不渲染。notoc 仍是页面级 TOC 退出键。这些开关不改变署名、标签、系列、 翻页顺序、feed 或页尾组合；导轨在 xl 断点以下消失。

搜索、操作与运行时

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 返回额外 字符串。

内置操作 ID 包括 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_theme、 switch_language、switch_version 与 open_github。分享栏之外的 copy_link 只出现在命令面板中。站点通过 languages.<lang>.params.ui.command_palette.commands 配置的命令可以打开安全 URL，或调用内置 ID，绝不能注入 JavaScript。

命令面板有空状态、文本搜索状态与 > 命令状态；快捷链接来自导航。它没有历史、 语义搜索、个性化或远程回退。搜索查询留在浏览器内，默认不发送遥测。

OinkSurfaceCoordinator 协调命令面板、抽屉、根栏目、语言与版本菜单。各界面自行 管理焦点恢复与 Escape。键盘导航会忽略可编辑控件与模态框：/、\、f、c 打开搜索或命令；j/k 移动标题；q/e 翻页；h 改变展示方式；l/y、 t、r 分别打开语言、主题与根栏目选项。侧栏 WASD/方向键导航使用真实焦点， 不会改写 Tab 顺序。

页面大纲从同一套标题模型与滚动容器计算后的 scroll-padding-top 推导光标和可见 标题范围；SVG 线条与圆点共享同一组动画值，不会漂移。禁止增加臆测性的 DOM 修复遍历。

分享

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 渲染；两者都可以做窄范围覆盖。各行顺序如下：

upstream_link 是页面级事实；cascade 有效，upstream_link: "" 表示退出。 其它上游事实按站点参数 → data/upstreams[upstream_source] → front matter 解析： upstream_name、upstream_copyright、upstream_license、upstream_notice， 以及可选的 upstream_ref、upstream_modified。存在链接时，前四项必填。无效或 残缺的署名会警告，而且不渲染法律声明；不支持的 URL 会被拒绝。发布门禁通过 --panicOnWarning 拒绝这类警告。

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 图标。图标词汇表由 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 系列条：默认收起的一行显示系列名和第 M/N 篇，展开后按阅读 顺序一行一篇，打印时默认展开。单篇系列与非 HTML 输出省略它。编号、交叉引用与 聚合输出仍属于 Book。

默认文章分类法徽章会排除保留的 authors 与 series，因为专属界面已经展示 它们。显式设置 params.taxonomy.page_header 可以恢复任意一项。

博客索引与页面组合

博客分区索引使用 params.ui.blog_index：默认的 list 与 cards 都是按最新优先 排列的一段扁平结果，共享 blog_index_size 分页；元数据行已经显示日期，所以不再 需要年份标题。table 把整个分区显示为日期、标题、标签行，不分页。卡片使用共享 首图、本地化日期/作者/分区元数据、标签与三行摘要。Term 与 taxonomy 页面保持 行列表。

params.ui.blog_index_toggle 为当前分页切片渲染三种形态，并允许读者循环切换。 配置值控制首次绘制，本地存储可以覆盖它，隐藏形态不加载图片。Front matter 或 cascade 可为每个分区覆盖站点模式。没有切换器的 table 仍是完整且不分页的归档。

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。

验证

bin/check-navigation-contract.py、bin/check-shell.py、JavaScript 测试、输出 golden 与消费站点浏览器套件覆盖导航、语言与子路径链接、博客变体、页尾顺序、 键盘行为、无障碍与响应式布局。