内容与自定义 on OINK 文档主题

Logo 与图片

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

添加 Logo

默认情况下，OINK 会在顶部导航栏起始位置（即最左侧）显示站点 Logo。把项目的 SVG Logo 放在 assets/icons/logo.svg，即可覆盖主题中的默认 Logo。

如果不希望顶部导航栏显示 Logo，请在项目配置中把站点参数 navbar_logo 设为 false：

[params.ui]
navbar_logo = false

params:
 ui:
 navbar_logo: false

{
 "params": {
 "ui": {
 "navbar_logo": false
 }
 }
}

Logo 样式的更多信息请参阅设置项目 Logo 与名称的样式。

代码仓库链接与页面信息

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

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

打印支持

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"
 ]
 }
}

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

导航与菜单

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

OINK 把 Hugo 的内容树和菜单模型组织成一套文档工作台：全局导航栏、可折叠且可调整宽度的分区侧边栏，以及可折叠的页面大纲。同一套结构适用于英文、中文和从右向左书写的语言。

全局导航栏由 Hugo 的 main 菜单与 OINK 自动生成的控件组成。根据配置和页面类型，其中可以显示版本、语言、颜色模式与搜索控件。

添加 `main` 菜单项

可以在页面 Front Matter 中定义菜单项：

---
title: 文档
linkTitle: 文档
menu:
 main:
 weight: 20
 pre: <i class="fa-solid fa-book" aria-hidden="true"></i>
---

权重越小，位置越靠前。站点级外部链接写法类似：

menus:
 main:
 - name: GitHub
 identifier: github
 weight: 50
 url: https://github.com/pgsty/oink
 pre: <i class="fa-brands fa-github" aria-hidden="true"></i>

需要在配置中引用菜单项时，应为其设置 identifier。name 或 linkTitle 可以按语言翻译，但标识符必须稳定。

配置 params.versions 后会显示版本选择器。条目可以表示标题、分隔线、正式版本、开发版本或站点变体：

短代码

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

短代码用于表达普通 Markdown 无法承载的行为。OINK 保留 Docsy 核心组件，并新增本地提供的图表、终端录像、信息图、轮播、卡片和折叠组件。浏览器运行时只在实际使用它们的页面加载。

标题、正文、列表、链接、表格和图片应优先使用 Markdown。短代码一旦投入使用，就成为内容 API 的一部分：修改名称或参数可能破坏所有调用它的页面。

短代码分隔符

Hugo 支持两种形式：

{{< name >}} 使用标准分隔符，原样传递内部内容；
{{% name %}} 使用 Markdown 分隔符，在周围内容的上下文中渲染内部 Markdown。

请采用各组件文档指定的形式。嵌套、缩进和空行都会影响结果，在列表和块引用中尤其如此。示例里的 /* ... */ 转义用于防止 Hugo 执行正在展示的短代码。

`blocks/*` 短代码

块短代码用于组合全宽落地页。color 参数使用 OINK/Bootstrap 语义颜色或项目自定义块样式，height 参数接受各组件说明的取值。

`blocks/cover`

使用页面包中匹配 *background* 的图片以及可选的 *logo* 创建首屏：

{{< blocks/cover title="OINK" subtitle="本地优先文档"
 color="dark" height="max" >}} [开始使用](/zh/docs/get-started/){ .btn
.btn-lg .btn-primary } {{< /blocks/cover >}}

image_anchor 和 logo_anchor 控制图片裁切位置，byline 用于标注图片来源。高度可取 auto、min、med、max 或 full。即使背景无法显示，首屏关键信息也必须保持可读。

分类法支持

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

OINK 在文档与博客分区中支持 Hugo 分类法。本页既展示默认布局，也可以用来测试生成链接的行为。

术语

使用分类法前，需要理解以下术语：

分类法（Taxonomy）：用于对内容进行分类的体系，例如标签、类别、项目、人物。
术语（Term）：分类法中的一个键。例如，在“项目”分类法中可以有“项目 A”和“项目 B”。
值（Value）：分配给某个术语的一项内容，例如属于特定项目的站点页面。

Hugo 文档提供了一个电影网站分类法示例。

参数

项目配置文件中有多项参数可以控制分类法功能。Hugo 默认启用 tags 与 categories 分类法。要禁用分类法，请在项目配置中添加：

disableKinds = ["taxonomy"]

disableKinds: [taxonomy]

{
 "disableKinds": [ "taxonomy" ]
}

保持默认设置时，Hugo 会生成 tags 与 categories 的分类法页面。如果要使用其他分类法，需要在配置文件中定义。如果希望自定义分类法与默认的 tags、categories 并存，也必须把默认分类法一并写入配置。每种分类法都需要提供单数与复数标签。

分析、用户反馈与 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 默认并推荐使用本地搜索。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 的内容模型：Markdown 承载信息，Front Matter 保存页面元数据，布局则把二者渲染成静态站点。本指南说明随项目提供的中英双语样例站采用的内容约定。

内容根目录

站点内容位于 content/ 目录下。多语言站点既可以分别使用 content/en/、content/zh/ 等内容根目录，也可以在同一棵挂载目录中使用语言后缀。本仓库采用后一种形式：

content/docs/content/
├── adding-content.md
└── adding-content.zh.md

英文文件是源页面，.zh.md 文件是对应的简体中文译文。Hugo 解析语言后缀后，二者具有相同的逻辑路径。

生成文件以及必须逐字节复制的文件不应放入内容树，而应放入 static/；详见添加静态内容。

内容分区与模板

内容根目录下的每个一级目录都是 Hugo 分区。OINK 提供以下布局：

docs：带分区树、目录、面包屑、上一篇/下一篇导航和仓库链接的文档页；
blog：带日期、分类元数据、Feed 和时间倒序列表的文章页；
community：展示项目与贡献者链接的社区页；
默认页面：不显示文档侧边栏的落地页。

Hugo 根据内容所属分区选择布局，因此 content/docs/ 下的页面会使用 docs 布局。只有确实要复用其他分区布局时，才在 Front Matter 中设置 type。

自定义分区

在内容根目录下新建目录；默认布局无法满足需求时，再为页面指定类型：

---
title: 架构决策
description: 项目已经采纳的设计决策。
type: docs
weight: 30
---

如果某项行为适用于整个分区，应在 _index.md 的 cascade 中设置共享值，避免每页重复。只有现有 OINK 布局与 Partial 均不适用时，才在项目的 layouts/ 下新增布局。

图表与公式

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

OINK 支持 KaTeX、Mermaid、Markmap、PlantUML 和 Diagrams.net。KaTeX、Mermaid 与 Markmap 使用构建期能力或主题随附的同源资源。PlantUML 和 Diagrams.net 编辑器需要显式配置服务端点；主题不会静默使用公共服务。

使用 KaTeX 支持 LaTeX

KaTeX 可以在 Web 上渲染 TeX 数学公式。Hugo 内置的 KaTeX 支持可以在构建期间渲染公式，因此读者不需要连接远程数学服务。

行内公式

行内公式使用 Goldmark 中配置的 passthrough 分隔符。条件允许时，应把公式前后的空格与标点留在公式之外。

独立显示公式

使用 math 代码块独立显示公式：

```math
E = mc^2
```

E = mc^2

启用 KaTeX 支持

math 与 chem 代码块会自动使用主题渲染钩子。对于行内公式和使用分隔符的公式，请启用 Goldmark 的 passthrough 扩展，并设置适合站点的分隔符。随仓库提供的 oink.pgsty.com 配置展示了方括号、双美元符号和圆括号分隔符。

外观与风格

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

OINK 在 Bootstrap 与 Docsy 基础上提供完整的视觉系统，并将字体、图标、样式和浏览器端代码全部本地化。使用方无需重建 Node 依赖树，就能通过设计变量和项目样式完成定制。

项目样式

Hugo Extended 通过 Hugo Pipes 编译主题 SCSS。项目覆盖项会进入同一个资源包，因此生产构建可以对一份同源样式表完成压缩、指纹和完整性校验。

项目样式文件

在站点的 assets/scss/ 目录中覆盖以下文件：

文件	用途
`_variables_project.scss`	在 Bootstrap 与 OINK 默认值之前设置变量
`_variables_project_after_bs.scss`	设置依赖 Bootstrap 定义的变量或映射
`_styles_project.scss`	在主题组件样式之后加载项目选择器

先从最小覆盖项开始：

// assets/scss/_variables_project.scss
$primary: #315f8f;
$secondary: #b4762e;

// assets/scss/_styles_project.scss
.td-content {
 --td-content-max-width: 78ch;
}

普通品牌定制不要直接修改纳管的 Bootstrap、Font Awesome 或本地字体文件。主题更新会覆盖这些改动，也会模糊依赖边界。

高级样式定制

OINK 的 SCSS 导入顺序如下：

Bootstrap 函数；
项目变量；
OINK 默认值与 Bootstrap；
Bootstrap 之后的项目变量；
OINK 组件与本地品牌层；
项目样式。

稳定的设计决策应通过变量或 CSS 自定义属性表达。没有合适设计变量时才覆盖选择器，而且作用域应尽量缩小到具体组件。许多颜色会随主题变化，因此必须检查浅色与深色输出。

文档版本管理

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"
 }
 ]
 }
}

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

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。

内容与自定义 on OINK 文档主题

Logo 与图片

添加 Logo

代码仓库链接与页面信息

链接配置

github_repo

github_subdir（可选）

打印支持

导航与菜单

站点导航栏

添加 main 菜单项

版本菜单

短代码

短代码分隔符

blocks/* 短代码

blocks/cover

分类法支持

术语

参数

分析、用户反馈与 SEO

添加分析

配置

用户反馈

反馈数据有什么用？

配置

搜索

使用 Lunr 的本地搜索

测试前构建索引

配置结果摘要与数量限制

排除页面

添加内容

内容根目录

内容分区与模板

自定义分区

图表与公式

使用 KaTeX 支持 LaTeX

行内公式

独立显示公式

启用 KaTeX 支持

外观与风格

项目样式

项目样式文件

高级样式定制

文档版本管理

添加版本下拉菜单

AI 智能体支持

功能

启用 Markdown 输出

让页面退出 Markdown 输出

`github_repo`

`github_subdir`（可选）

添加 `main` 菜单项

`blocks/*` 短代码

`blocks/cover`