高级 on OINK

键盘导航

Mon, 01 Jan 0001 00:00:00 +0000

OINK 在文档、博客与 Swagger 页面内置单键键盘导航。默认开启，所有按键都会为输入让行，站点或单页均可关闭。设计上，当前页就是侧栏的隐含光标，章节跳转复用渲染后的页面目录，所有动作都委托给主题的既有机制，不维护第二套平行状态。

快捷键

w、s、a、d 一步到位地驾驭侧边栏：当前页面所在项就是隐含的起点，首次按键即从那里移动或折叠。焦点行的底色比“当前页”药丸更深一档，“我在哪”与“光标在哪”一眼可辨。窄屏下侧栏收进抽屉时，首次按键会先打开抽屉；桌面侧栏若已折叠，同一次按键会先恢复侧栏，并继续完成所请求的移动或折叠。

按键	行为
`w` / `↑`	焦点移到上一个可见项
`s` / `↓`	焦点移到下一个可见项
`a` / `←`	折叠焦点分组；叶子节点则跳到父级
`d` / `→`	展开焦点分组；已展开则进入第一个子项
`Enter` / `Space` / `g`	打开焦点页面
`Escape`	焦点返回正文

方向键只在焦点位于侧边栏内时作用于树——在正文中保持浏览器原生滚动行为。RTL 语言下 ←/→ 随阅读方向对调。

阅读

按键	行为
`j` / `k`	沿页面目录跳到下一节 / 上一节
`q` / `e`	按侧边栏顺序前往上一篇 / 下一篇
`h`	隐藏/恢复全部导航外壳（专注阅读模式）

j 与 k 跟右侧目录同源，以固定 100ms 的快速 ease-out 滑动落位；连续按键时，每次都会继续前进一个目录项，无需等待上一段动画。深入某一节时 k 会先回到本节起点，无标题的页面退化为同样的短促滑动。h 的阅读模式在会话内被记住，用 h 会隐藏顶部导航栏、左右栏、浮动控件与页脚。状态会在同一标签页会话中于首帧前恢复，因此用 q/e 翻页既不会丢失也不会闪烁；侧栏主动隐藏时，WASD 保持静默。

搜索与命令面板

Mon, 01 Jan 0001 00:00:00 +0000

OINK 默认且推荐本地搜索：Hugo 为每种语言生成独立索引，Lunr 与 CJK 回退都从同源资源提供。站点不需要公共爬虫、外部账户、CDN 或网络连接就能完成构建和搜索。

Google Custom Search 与 Algolia DocSearch 作为兼容集成保留，默认关闭。同一时间只能启用一种搜索实现。

启用本地搜索

params:
  offlineSearch: true
  offlineSearchIndex: summary # summary | content
  offlineSearchSummaryLength: 120
  offlineSearchMaxResults: 12

offlineSearch , boolean , required , default: false: 启用本地索引与命令面板。不要同时配置 gcs_engine_id 或 params.search.algolia。
offlineSearchIndex , string , default: content: summary 只索引标题、描述与摘要；content 索引全部正文。千页级站点应该用 summary——content 会产生数 MB 的索引，读者每次搜索都要先下载它。
offlineSearchSummaryLength , integer , default: 70: 结果摘要的长度。
offlineSearchMaxResults , integer , default: 10: 最多显示几条结果。数值要保证对话框在移动端仍然好用。

构建后每种语言会生成一个索引：

TEXT

public/offline-search-index.en.json
public/offline-search-index.zh.json

子路径部署时，确认浏览器是从配置的 baseURL

下请求索引，而不是域名根目录。这是搜索「没结果」最常见的原因，而且页面本身看起来是正常的。

打印支持

Mon, 01 Jan 0001 00:00:00 +0000

大多数浏览器都能很好地打印单篇文档，因为页面样式会从打印输出中移除导航外壳。因此，打印单个页面交给浏览器自带的 Cmd/Ctrl+P 即可，OINK 不再提供页面级的打印操作。

有些站点适合启用“打印整节”功能（本用户指南就是如此）。选择后，系统会把当前顶层分区（例如本页所在的“高级特性”）连同全部子页面和子分区渲染为适合打印的格式，并附上该分区的完整目录。

要启用此功能，请在站点的 hugo.toml、hugo.yaml 或 hugo.json 中，为 section 类型添加 print 输出格式：

配置文件：

hugo.toml

TOML


[outputs]
section = [ "HTML", "RSS", "print" ]

hugo.yaml

YAML


outputs:
  section:
    - HTML
    - RSS
    - print

hugo.json

JSON


{
  "outputs": {
    "section": [
      "HTML",
      "RSS",
      "print"
    ]
  }
}

随后，页面操作菜单中会出现「打印整个分区」条目，命令面板中则以 print_section 的形式出现。

AI 智能体支持

Mon, 01 Jan 0001 00:00:00 +0000

早期评估

本页介绍的功能仍处于实验阶段，适合早期采用和评估。后续版本可能会调整输出细节和验证范围。要跟踪智能体支持功能的阶段性演进，请参阅 Improve support for AI-agent doc consumption #2614。

功能

站点显式启用后，OINK 会提供以下面向用户和机器可读的行为：

支持 Markdown 输出格式。项目的 outputs 配置决定哪些页面类型发布 Markdown。
发现机制：页面 HTML 的 header 会包含指向该页 Markdown 版本的 rel="alternate" 链接。
复制 Markdown 文本 / 查阅 Markdown 源码：当页面存在 Markdown 输出时，页面操作可以复制或打开该版本。复制是面包屑行中拆分按钮的左半边，其余入口在它的菜单里。
在 ChatGPT / Claude 中打开：只有显式启用 params.ui.page_context_menu.assistant_links 后，有源文件的页面操作才会把当前浏览器 URL 交给相应助手。OINK 只在读者激活链接时构造提示词，并保留实际部署域名、查询参数与片段。完整 URL 随后会离开本站；请勿在 URL 中放置秘密信息，并披露这一第三方边界。页面正文不会被上传。
查阅编辑历史：当 github_repo 与仓库路径可用时，打开当前源文件的提交历史。
llms.txt：位于站点根目录的内容清单文件。

本页其余部分介绍如何启用各项功能，并结合示例讨论相应的验证与指标。

YAML

params:
  ui:
    page_context_menu:
      assistant_links: true

可用布尔型 assistant_links front matter 按页面覆盖这一选择。

使用 giscus 添加评论

Mon, 01 Jan 0001 00:00:00 +0000

OINK 在 params.comments 下提供与 Hextra 兼容的评论配置，并通过该配置支持 giscus。giscus 会为每个内容页关联一条由 GitHub Discussions 保存的评论线程，读者通过 GitHub OAuth 登录后即可发表评论。

giscus 如何工作

页面加载时，giscus 会在配置的仓库中查找与当前页面匹配的 Discussion。如果没有找到，读者首次发表评论或表态时，giscus bot 会自动创建一条。维护者直接在 GitHub Discussions 中审核和管理评论。

所有人都可以阅读公开评论。读者发表评论时，选择 使用 GitHub 登录，并授权 giscus app 代表自己发帖。OINK 不会索取或保存读者的 GitHub 密码或访问令牌。

外部服务

giscus 是需要显式启用的在线集成。启用评论的页面会从 https://giscus.app 加载脚本和 iframe，因此无法在网络隔离环境中运行。必要时，请在消费站点的隐私与安全政策中说明这条外部数据边界。

准备 GitHub 仓库

配置 OINK 前，请完成以下准备：

使用公开 GitHub 仓库保存评论线程。访客无法读取私有仓库中的 Discussions。
在仓库的 Settings > Features 中启用 GitHub Discussions。
为该仓库安装 giscus GitHub App。没有此 App，访客无法评论或表态。
选择一个 Discussion 分类。giscus 推荐使用 Announcements 类型，以便只有维护者和 giscus bot 能创建新的 Discussions。

仓库 ID 与分类 ID 是公开标识符，不是凭据。不要在 Hugo 配置中加入 GitHub personal access token、OAuth secret 或密码。

分析、用户反馈与 SEO

Mon, 01 Jan 0001 00:00:00 +0000

OINK 默认不会连接分析、表单、评论或广告服务。这些集成属于站点决策：必须显式启用、记录数据边界，并根据用户与站点所在司法辖区提供必要的同意机制或政策说明。

添加分析

Hugo 为分析服务提供嵌入模板。站点配置 Google Analytics 后，页面浏览量与自定义事件等浏览器使用信息会发送给 Google。这与完全网络隔离的运行环境不兼容，也可能不符合严格的同源内容安全策略（CSP）。

配置

取得站点的 Google Analytics measurement ID，然后使用 Hugo 当前的服务配置：

YAML

services:
  googleAnalytics:
    id: G-YOUR-ID

不要同时设置已经弃用的顶层 googleAnalytics 键。通常只有 Hugo production 环境才会输出分析代码。发布前，请构建生产预览，并检查 HTML 与浏览器网络日志。

禁用分析后，OINK 不会发起 Google Analytics 请求。应彻底删除相关配置，而不是填写虚假 ID。

用户反馈

OINK 可以在文档页底部显示“本页是否有帮助？”小组件。它提供是与否两个操作，随后显示配置好的响应；响应通常包含创建文档 issue 的链接。

图 1：页面反馈组件

即使不启用分析，响应仍然可以发挥作用：它可以把读者引导到 issue 模板、讨论区、电子邮箱或站点自有的其他反馈渠道。只有站点配置了适当目标后，才会发生数据收集和事件上报。

反馈数据有什么用？

应结合上下文理解反馈，不能把单一分数当作结论。访问量高且反复收到负面反馈的页面是值得优先复查的候选；高评分页面则可能揭示值得在其他页面验证的模式。

应尽可能采用聚焦的编辑变更。例如，只更新一篇过时教程，或者把一小组页面的代码示例提前，然后在合适的时间范围内比较反馈。同时记录发布事件、流量变化、支持事件和其他可能解释变化的因素。

反馈只能提供方向性证据，不能取代用户研究、无障碍评审、支持数据或技术验证。

高级功能

Mon, 01 Jan 0001 00:00:00 +0000

这一章介绍主题的高级能力。无需外部服务的键盘导航默认开启；会改变站点策略或向第三方传输数据的能力仍需显式启用——主题提供实现，但不替站点做策略决定。

本章内容

键盘导航：完整单键映射、焦点规则与按页关闭方法
搜索与命令面板：本地索引、搜索排序、Cmd/Ctrl-K、/ 完整搜索与 \ 命令模式
打印输出：整个分区的打印视图
AI 与 Agent 支持：Markdown 输出、llms.txt、页面操作
评论：giscus 集成
分析统计：Google Analytics 与其他统计服务

默认值遵循风险边界

能力	参数	默认
键盘导航	`params.ui.keyboard_nav.enable`	`true`
本地搜索	`params.offlineSearch`	`false`
明暗切换	`params.ui.showLightDarkModeMenu`	`false`
图片缩放	`params.ui.image_zoom.enable`	`false`
评论	`params.comments.enable`	`false`
页面反馈	`params.ui.feedback.enable`	`false`
助手链接	`params.ui.page_context_menu.assistant_links`	`false`

这不是保守，而是边界问题：是否把读者数据发给第三方，是站点的决定，不是主题的。

同理，PlantUML 和 Draw.io 缺少显式端点配置时会中断构建，而不是悄悄用一个公共服务。