高级特性 on OINK

多语言支持

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

OINK 使用 Hugo 的多语言页面模型，不依赖某个站点专属的域名或模板假设。随仓库提供的站点将英文设为首要语言，将简体中文（zh）设为第二语言。

配置语言

在 hugo.yaml 中定义默认语言与所有启用的语言：

defaultContentLanguage: en

languages:
  en:
    label: English
    locale: en-US
    weight: 1
    title: Product Documentation
    params:
      description: Product guides and reference
  zh:
    label: 简体中文
    locale: zh-CN
    weight: 2
    title: 产品文档
    params:
      description: 产品指南与参考资料
      time_format_default: 2006年1月2日
      time_format_blog: 2006年1月2日

weight 同时决定语言排序和选择器顺序。label 使用该语言自己的文字显示。locale 为 HTML、备用链接和 Open Graph 元数据提供符合标准的语言标签。

语言专属参数会覆盖全局值；未定义的参数继承全局值。菜单标签不同时，请在每种语言下分别定义菜单。

搜索

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

OINK 默认并推荐使用本地搜索。Hugo 会为每种语言生成独立索引；主题从同源资源提供 Lunr 及其 CJK 回退。站点无需公共爬虫、外部账户、CDN 或网络连接，即可完成构建和搜索。

Google Custom Search 与 Algolia DocSearch 仍作为兼容的在线集成保留。它们默认关闭；只有站点明确接受相应的外部请求、索引方式、可用性与隐私边界时，才应启用。

同一时间只能启用一种搜索实现。

使用 Lunr 的本地搜索

在 hugo.yaml 中启用本地搜索：

params:
  offlineSearch: true

不要同时配置 gcs_engine_id 或 params.search.algolia。生产构建完成后，输出中会为每种语言生成一个索引，例如：

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

浏览器加载当前语言的索引，并在不离开页面的情况下显示结果。中文内容使用 OINK 的 CJK 回退，不依赖以空格分词。

测试前构建索引

启动预览前先执行常规构建：

hugo --gc
hugo server --disableFastRender

如果索引变化时 server 已经在运行，请将其重启。对于子路径部署，请确认浏览器从配置的 baseURL 下请求索引，而不是从域名根目录请求。

配置结果摘要与数量限制

设置摘要长度和最大结果数：

params:
  offlineSearch: true
  offlineSearchSummaryLength: 120
  offlineSearchMaxResults: 12

所选限制应确保搜索对话框在移动设备上保持流畅。摘要用于帮助发现内容，不能替代认真编写的页面描述。

排除页面

在页面 front matter 中设置 exclude_search: true：

文档版本管理

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

根据项目的发布和版本管理方式，你可能需要让用户访问旧版文档。旧版本的具体部署方式由你决定。本页介绍 OINK 提供的功能：在各个文档版本之间导航，并在归档站点上显示信息横幅。

如果在 hugo.toml、hugo.yaml 或 hugo.json 中添加 [params.versions]，OINK 会在顶部导航栏加入版本下拉选择器。请为每个需要加入菜单的版本指定 URL 和名称，例如：

# Add your release versions here
[[params.versions]]
  version = "master"
  url = "https://master.kubeflow.org"

[[params.versions]]
  version = "v0.2"
  url = "https://v0-2.kubeflow.org"

[[params.versions]]
  version = "v0.3"
  url = "https://v0-3.kubeflow.org"

params:
  versions:
    - version: master
      url: 'https://master.kubeflow.org'
    - version: v0.2
      url: 'https://v0-2.kubeflow.org'
    - version: v0.3
      url: 'https://v0-3.kubeflow.org'

{
  "params": {
    "versions": [
      {
        "version": "master",
        "url": "https://master.kubeflow.org"
      },
      {
        "version": "v0.2",
        "url": "https://v0-2.kubeflow.org"
      },
      {
        "version": "v0.3",
        "url": "https://v0-3.kubeflow.org"
      }
    ]
  }
}

别忘了加入当前版本，这样用户才能返回！

使用 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 当前的服务配置：

services:
  googleAnalytics:
    id: G-YOUR-ID

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

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

用户反馈

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

图 1：页面反馈组件

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

反馈数据有什么用？

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

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

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

配置

OINK 默认关闭该小组件。请设置全局默认值，并配置本地化响应。英文配置如下：

params:
  ui:
    feedback:
      enable: false
languages:
  en:
    params:
      ui:
        feedback:
          yes: >-
            Glad to hear it! Please <a
            href="https://github.com/OWNER/REPOSITORY/issues/new">tell us how we
            can improve</a>.
          no: >-
            Sorry to hear that. Please <a
            href="https://github.com/OWNER/REPOSITORY/issues/new">tell us how we
            can improve</a>.

简体中文字符串放在 languages.zh.params 下：

代码仓库链接与页面信息

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

OINK 的文档与博客布局可以显示指向当前页面源码仓库的链接：

查看页面源码：打开源文件。
编辑本页：打开可编辑的源码视图。
创建子页面：在当前页面下新建文件，并可使用站点的 assets/stubs/new-page-template.md 模板。
创建文档 issue：携带页面上下文，在文档仓库中创建 issue。
创建项目 issue：可选地把 issue 提交到另一个产品仓库。

内置 URL 模式面向 GitHub 风格的代码仓库。如果使用其他兼容托管服务，请逐项验证；如果 URL 结构不同，应覆盖相应 partial。

链接配置

典型站点配置如下：

params:
  github_repo: https://github.com/OWNER/DOCS
  github_project_repo: https://github.com/OWNER/PRODUCT
  github_branch: main
  github_subdir: site

当内容来自多个代码仓库时，可以在全局、单种语言、分区 cascade 或页面 front matter 中设置这些值。

`github_repo`

文档源码仓库 URL。它用于生成查看、编辑、创建子页面和创建文档 issue 链接：

params:
  github_repo: https://github.com/pgsty/oink

省略后将隐藏从仓库派生的页面操作。如果页面源码实际位于消费站点，不要把它错误地指向主题仓库。

`github_subdir`（可选）

设置从仓库根目录到 Hugo 站点源码的路径。本项目把站点存放在 oink.pgsty.com 中：

params:
  github_subdir: oink.pgsty.com

该值是仓库内路径，不是本地绝对路径；除非内容目录就是实际站点根目录，否则也不能直接填写内容目录。

`github_project_repo`（可选）

设置另一个产品仓库，以显示 创建项目 issue：

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”链接。
llms.txt：位于站点根目录的内容清单文件。

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

启用 Markdown 输出

Hugo 提供多种内置输出格式，其中包括 markdown。要启用 Markdown 输出，请在 Hugo 的 outputs 配置中，把 markdown 加入需要支持的页面类型。例如：

outputs:
  home: [HTML, markdown]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]

[outputs]
home = [ "HTML", "markdown" ]
page = [ "HTML", "markdown" ]
section = [ "HTML", "RSS", "print", "markdown" ]

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

让页面退出 Markdown 输出

提示

默认情况下，无论 Hugo 的 outputs 映射位于多文件站点配置还是页面 front matter 中，它都会对每种页面类型执行 完整替换，而不是合并¹。添加 markdown 时，请保留站点已经依赖的所有格式，例如以上示例中分区使用的 RSS 和 print。

打印支持

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

大多数浏览器都能很好地打印单篇文档，因为页面样式会从打印输出中移除导航外壳。

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

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

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

outputs:
  section:
    - HTML
    - RSS
    - print

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

随后，站点右侧导航中会显示“打印整节”链接。

高级特性 on OINK

多语言支持

配置语言

搜索

使用 Lunr 的本地搜索

测试前构建索引

配置结果摘要与数量限制

排除页面

文档版本管理

添加版本下拉菜单

使用 giscus 添加评论

giscus 如何工作

准备 GitHub 仓库

分析、用户反馈与 SEO

添加分析

配置

用户反馈

反馈数据有什么用？

配置

代码仓库链接与页面信息

链接配置

github_repo

github_subdir（可选）

github_project_repo（可选）

AI 智能体支持

功能

启用 Markdown 输出

让页面退出 Markdown 输出

打印支持

`github_repo`

`github_subdir`（可选）

`github_project_repo`（可选）